├── .prettierignore
├── .gitignore
├── .prettierrc
├── tsconfig.json
├── preact
    ├── package.json
    └── dist
    │   ├── gundb-react-hooks.modern.js
    │   └── gundb-react-hooks.modern.js.map
├── LICENSE.md
├── package.json
├── docs
    ├── AuthProvider.md
    ├── useAuth.md
    ├── useGunState.md
    ├── useGunKeyAuth.md
    ├── useGunNamespace.md
    ├── useGunCollectionStatePaginated.md
    ├── useGunCollectionState.md
    ├── useGunOnNodeUpdated.md
    ├── useGunKeys.md
    └── useGun.md
├── CHANGELOG.md
├── dist
    └── index.d.ts
└── README.md


/.prettierignore:
--------------------------------------------------------------------------------
1 | dist


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | .rts2*


--------------------------------------------------------------------------------
/.prettierrc:
--------------------------------------------------------------------------------
1 | {
2 |   "semi": true,
3 |   "singleQuote": true
4 | }
5 | 


--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "compilerOptions": {
 3 |     "target": "es5",
 4 |     "lib": ["dom", "dom.iterable", "esnext"],
 5 |     "allowJs": true,
 6 |     "skipLibCheck": true,
 7 |     "esModuleInterop": true,
 8 |     "allowSyntheticDefaultImports": true,
 9 |     "strict": true,
10 |     "forceConsistentCasingInFileNames": true,
11 |     "module": "esnext",
12 |     "moduleResolution": "node",
13 |     "resolveJsonModule": true,
14 |     "isolatedModules": true,
15 |     "noImplicitAny": false,
16 |     "noEmit": true
17 |   },
18 |   "include": ["src"]
19 | }
20 | 


--------------------------------------------------------------------------------
/preact/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "@altrx/gundb-react-hooks",
 3 |   "version": "0.9.8",
 4 |   "description": "GUNDB hooks for React/Preact",
 5 |   "scripts": {},
 6 |   "repository": {
 7 |     "type": "git",
 8 |     "url": "git+https://github.com/alterx/gundb-react-hooks.git"
 9 |   },
10 |   "author": "Carlos Vega",
11 |   "license": "MIT",
12 |   "bugs": {
13 |     "url": "https://github.com/alterx/gundb-react-hooks/issues"
14 |   },
15 |   "sideEffects": false,
16 |   "browser": "dist/gundb-react-hooks.umd.js",
17 |   "umd:main": "dist/gundb-react-hooks.umd.js",
18 |   "jsnext:main": "dist/gundb-react-hooks.modern.js",
19 |   "main": "dist/gundb-react-hooks.js",
20 |   "module": "dist/gundb-react-hooks.module.js",
21 |   "unpkg": "dist/gundb-react-hooks.umd.js",
22 |   "source": "./src/index.ts",
23 |   "types": "./dist/index.d.ts",
24 |   "typings": "./dist/index.d.ts",
25 |   "peerDependencies": {
26 |     "preact": ">=10"
27 |   }
28 | }
29 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | Copyright 2020 Carlos Vega
2 | 
3 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4 | 
5 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6 | 
7 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
8 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "@altrx/gundb-react-hooks",
 3 |   "version": "1.0.0rc3",
 4 |   "description": "Type-safe, performant GunDB hooks for React/Preact with authentication, error handling, and debugging utilities",
 5 |   "browser": "./dist/gundb-react-hooks.umd.js",
 6 |   "umd:main": "./dist/gundb-react-hooks.umd.js",
 7 |   "jsnext:main": "./dist/gundb-react-hooks.modern.js",
 8 |   "main": "./dist/gundb-react-hooks.js",
 9 |   "module": "./dist/gundb-react-hooks.module.js",
10 |   "unpkg": "./dist/gundb-react-hooks.umd.js",
11 |   "source": "./src/index.ts",
12 |   "types": "./dist/index.d.ts",
13 |   "typings": "./dist/index.d.ts",
14 |   "exports": {
15 |     ".": {
16 |       "types": "./dist/index.d.ts",
17 |       "import": "./dist/gundb-react-hooks.module.js",
18 |       "require": "./dist/gundb-react-hooks.js"
19 |     },
20 |     "./preact": {
21 |       "types": "./preact/dist/index.d.ts",
22 |       "import": "./preact/dist/gundb-react-hooks.module.js",
23 |       "require": "./preact/dist/gundb-react-hooks.js"
24 |     }
25 |   },
26 |   "repository": {
27 |     "type": "git",
28 |     "url": "git+https://github.com/alterx/gundb-react-hooks.git"
29 |   },
30 |   "keywords": [
31 |     "preact",
32 |     "react",
33 |     "gun",
34 |     "gunDB",
35 |     "graph",
36 |     "document",
37 |     "key",
38 |     "value",
39 |     "relational",
40 |     "datastore",
41 |     "database",
42 |     "engine",
43 |     "realtime",
44 |     "decentralized",
45 |     "peer-to-peer",
46 |     "distributed",
47 |     "P2P",
48 |     "OSS",
49 |     "embedded",
50 |     "localstorage",
51 |     "S3",
52 |     "typescript",
53 |     "hooks",
54 |     "error-handling",
55 |     "type-safe",
56 |     "performance",
57 |     "debugging",
58 |     "authentication",
59 |     "auth",
60 |     "login",
61 |     "keypair",
62 |     "sea",
63 |     "cryptography"
64 |   ],
65 |   "files": [
66 |     "dist",
67 |     "preact/dist"
68 |   ],
69 |   "scripts": {
70 |     "build": "rimraf dist && npm run build:preact && npm run build:react",
71 |     "build:react": "microbundle --define process.env.NODE_ENV=production --external react --name @altrx/gundb-react-hooks --no-compress --output dist/",
72 |     "build:preact": "microbundle --define process.env.NODE_ENV=production --external preact --name @altrx/gundb-react-hooks --no-compress --output preact/dist --alias react=preact/hooks",
73 |     "dev": "microbundle watch",
74 |     "test": "echo \"Error: no test specified\" && exit 1"
75 |   },
76 |   "author": "Carlos Vega",
77 |   "license": "MIT",
78 |   "peerDependencies": {
79 |     "react": ">=16.12.0",
80 |     "react-dom": ">=16.12.0"
81 |   },
82 |   "devDependencies": {
83 |     "@skypack/package-check": "^0.2.2",
84 |     "husky": "^9.1.7",
85 |     "microbundle": "^0.15.1",
86 |     "prettier": "^3.4.2",
87 |     "pretty-quick": "^4.0.0",
88 |     "react": "^16.13.1",
89 |     "react-dom": "^16.13.1",
90 |     "rimraf": "^6.0.1"
91 |   },
92 |   "husky": {
93 |     "hooks": {
94 |       "pre-commit": "pretty-quick --staged"
95 |     }
96 |   }
97 | }
98 | 


--------------------------------------------------------------------------------
/docs/AuthProvider.md:
--------------------------------------------------------------------------------
  1 | # AuthProvider
  2 | 
  3 | A React context provider that manages GunDB authentication state, key generation, and secure storage across your application.
  4 | 
  5 | ## Overview
  6 | 
  7 | `AuthProvider` automatically handles key pair generation, secure storage, authentication flow, and cross-platform storage abstraction. It serves as the foundation for the authentication system in GunDB React applications.
  8 | 
  9 | ## API Reference
 10 | 
 11 | ### Props
 12 | 
 13 | #### Required Props
 14 | 
 15 | | Prop       | Type              | Description                                        |
 16 | | ---------- | ----------------- | -------------------------------------------------- |
 17 | | `Gun`      | `any`             | Gun constructor function                           |
 18 | | `sea`      | `any`             | SEA (Security, Encryption, Authorization) instance |
 19 | | `storage`  | `Storage`         | Storage implementation for key persistence         |
 20 | | `gunOpts`  | `GunOptions`      | Configuration options for Gun instance             |
 21 | | `children` | `React.ReactNode` | Child components to wrap                           |
 22 | 
 23 | #### Optional Props
 24 | 
 25 | | Prop           | Type     | Default  | Description                              |
 26 | | -------------- | -------- | -------- | ---------------------------------------- |
 27 | | `keyFieldName` | `string` | `'keys'` | Storage key name for persisting keypairs |
 28 | 
 29 | ### Storage Interface
 30 | 
 31 | ```typescript
 32 | interface Storage {
 33 |   getItem: (key: string) => any;
 34 |   setItem: (key: string, data: string) => any;
 35 |   removeItem: (key: string) => any;
 36 | }
 37 | ```
 38 | 
 39 | ## Basic Usage
 40 | 
 41 | ### Simple Setup
 42 | 
 43 | ```typescript
 44 | import { AuthProvider } from '@altrx/gundb-react-hooks';
 45 | import Gun from 'gun';
 46 | import 'gun/sea';
 47 | 
 48 | function App() {
 49 |   return (
 50 |     <AuthProvider
 51 |       Gun={Gun}
 52 |       sea={Gun.SEA}
 53 |       storage={localStorage}
 54 |       gunOpts={{
 55 |         peers: ['http://localhost:8765/gun'],
 56 |         localStorage: false
 57 |       }}
 58 |     >
 59 |       <YourApp />
 60 |     </AuthProvider>
 61 |   );
 62 | }
 63 | ```
 64 | 
 65 | ## Advanced Usage
 66 | 
 67 | ### Platform-Specific Storage
 68 | 
 69 | ### Web (localStorage)
 70 | 
 71 | ```typescript
 72 | <AuthProvider
 73 |   storage={localStorage}
 74 |   // ... other props
 75 | />
 76 | ```
 77 | 
 78 | ### React Native (AsyncStorage)
 79 | 
 80 | ```typescript
 81 | import AsyncStorage from '@react-native-async-storage/async-storage';
 82 | 
 83 | const asyncStorage = {
 84 |   getItem: async (key: string) => {
 85 |     return await AsyncStorage.getItem(key);
 86 |   },
 87 |   setItem: async (key: string, data: string) => {
 88 |     await AsyncStorage.setItem(key, data);
 89 |   },
 90 |   removeItem: async (key: string) => {
 91 |     await AsyncStorage.removeItem(key);
 92 |   }
 93 | };
 94 | 
 95 | <AuthProvider
 96 |   storage={asyncStorage}
 97 |   // ... other props
 98 | />
 99 | ```
100 | 
101 | ### Node.js (File System)
102 | 
103 | ```typescript
104 | import fs from 'fs';
105 | import path from 'path';
106 | 
107 | const fileStorage = {
108 |   getItem: (key: string) => {
109 |     try {
110 |       const filePath = path.join(__dirname, `${key}.json`);
111 |       return fs.readFileSync(filePath, 'utf8');
112 |     } catch {
113 |       return null;
114 |     }
115 |   },
116 |   setItem: (key: string, data: string) => {
117 |     const filePath = path.join(__dirname, `${key}.json`);
118 |     fs.writeFileSync(filePath, data);
119 |   },
120 |   removeItem: (key: string) => {
121 |     const filePath = path.join(__dirname, `${key}.json`);
122 |     try {
123 |       fs.unlinkSync(filePath);
124 |     } catch {
125 |       // File doesn't exist, ignore
126 |     }
127 |   }
128 | };
129 | 
130 | <AuthProvider
131 |   storage={fileStorage}
132 |   // ... other props
133 | />
134 | ```
135 | 
136 | ### Secure Storage (Encrypted)
137 | 
138 | ```typescript
139 | import CryptoJS from 'crypto-js';
140 | 
141 | const secureStorage = {
142 |   getItem: (key: string) => {
143 |     const encrypted = localStorage.getItem(key);
144 |     if (!encrypted) return null;
145 | 
146 |     try {
147 |       const decrypted = CryptoJS.AES.decrypt(encrypted, 'your-secret-key');
148 |       return decrypted.toString(CryptoJS.enc.Utf8);
149 |     } catch {
150 |       return null;
151 |     }
152 |   },
153 |   setItem: (key: string, data: string) => {
154 |     const encrypted = CryptoJS.AES.encrypt(data, 'your-secret-key').toString();
155 |     localStorage.setItem(key, encrypted);
156 |   },
157 |   removeItem: (key: string) => {
158 |     localStorage.removeItem(key);
159 |   }
160 | };
161 | 
162 | <AuthProvider
163 |   storage={secureStorage}
164 |   // ... other props
165 | />
166 | ```
167 | 
168 | ## Error Handling
169 | 
170 | ### Comprehensive Error Management
171 | 
172 | ```typescript
173 | function AppWithErrorHandling() {
174 |   return (
175 |     <ErrorBoundary>
176 |       <AuthProvider
177 |         Gun={Gun}
178 |         sea={Gun.SEA}
179 |         storage={localStorage}
180 |         gunOpts={gunOpts}
181 |       >
182 |         <App />
183 |       </AuthProvider>
184 |     </ErrorBoundary>
185 |   );
186 | }
187 | 
188 | class ErrorBoundary extends React.Component {
189 |   componentDidCatch(error: Error, errorInfo: any) {
190 |     if (error.message.includes('Provide gunOpts, Gun and sea')) {
191 |       console.error('AuthProvider configuration error:', error);
192 |       // Handle configuration errors
193 |     }
194 |   }
195 | 
196 |   render() {
197 |     // Error UI
198 |     return this.state.hasError ? <ErrorComponent /> : this.props.children;
199 |   }
200 | }
201 | ```
202 | 
203 | ## Migration from v0.9.x
204 | 
205 | ### Before (v0.9.x)
206 | 
207 | ```typescript
208 | // Manual provider setup with limited features
209 | import { GunProvider } from '@altrx/gundb-react-auth';
210 | 
211 | <GunProvider gun={Gun} options={gunOpts}>
212 |   <App />
213 | </GunProvider>
214 | ```
215 | 
216 | ### After (v1.0.0)
217 | 
218 | ```typescript
219 | // Enhanced provider with built-in authentication
220 | import { AuthProvider } from '@altrx/gundb-react-hooks';
221 | 
222 | <AuthProvider
223 |   Gun={Gun}
224 |   sea={Gun.SEA}
225 |   storage={localStorage}
226 |   gunOpts={gunOpts}
227 | >
228 |   <App />
229 | </AuthProvider>
230 | ```
231 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
  1 | # Changelog
  2 | 
  3 | All notable changes to this project will be documented in this file.
  4 | 
  5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
  6 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
  7 | 
  8 | ## [1.0.0rc3] - 2025-08-22
  9 | 
 10 | ### Fixed
 11 | 
 12 | - exports in package.json
 13 | 
 14 | ## [1.0.0rc2] - 2025-08-22
 15 | 
 16 | ### Fixed
 17 | 
 18 | - Performance and compatibility issues.
 19 | 
 20 | ## [1.0.0rc1] - 2025-08-21
 21 | 
 22 | ### Added
 23 | 
 24 | - **`useGunCollectionStatePaginated`** - A high-performance, memory-efficient hook for managing paginated GunDB collections with smart caching, real-time updates, and comprehensive filtering/sorting capabilities.
 25 | 
 26 | ### Documentation
 27 | 
 28 | - Removed unused migration references
 29 | 
 30 | ## [1.0.0] - 2025-08-21
 31 | 
 32 | ### Major Release - Complete Rewrite
 33 | 
 34 | This release represents a significant overhaul of the library with breaking changes, improved TypeScript support, and enhanced developer experience.
 35 | It also consolidates the hooks and providers available at https://github.com/alterx/gundb-react-auth to provide an all emcompasing solution for GunDB and React integration.
 36 | 
 37 | ### Added
 38 | 
 39 | #### Type Safety
 40 | 
 41 | - **Comprehensive TypeScript definitions** for all GunDB operations
 42 | - **Proper interface definitions** (`IGunChainReference`, `IGunUserReference`)
 43 | - **Strong type constraints** with `ValidGunData` and `NodeData<T>`
 44 | - **Enhanced error types** with contextual information (`GunError`)
 45 | 
 46 | #### Error Handling & Reliability
 47 | 
 48 | - **Error states in all hooks** - hooks now return `{ error, isLoading, isConnected }`
 49 | - **Input validation** for all operations (validateNodeID, validateData)
 50 | - **Connection timeout handling** (5-second timeout with proper error reporting)
 51 | - **Graceful failure handling** with try-catch blocks and error recovery
 52 | - **Development warnings** for common misconfigurations
 53 | 
 54 | #### Performance Optimizations
 55 | 
 56 | - **Fixed memory leaks** in `useGunOnNodeUpdated` with proper cleanup tracking
 57 | - **Memoization** of expensive operations using `useMemo` and `useCallback`
 58 | - **Optimized re-renders** with better dependency management
 59 | - **Debounced handler cleanup** to prevent memory accumulation
 60 | 
 61 | #### New Hooks & Utilities
 62 | 
 63 | - **`useGunContext`** - Access Gun instance through React context
 64 | - **`useGunDebug`** - Development debugging with detailed logging
 65 | - **`useGunConnection`** - Monitor connection status and health
 66 | - **`GunProvider`** - Context provider for Gun instance management
 67 | - **`AuthProvider`** - Authentication provider with key management and storage (from https://github.com/alterx/gundb-react-auth)
 68 | - **`useAuth`** - Hook for accessing authentication state and methods (from https://github.com/alterx/gundb-react-auth)
 69 | 
 70 | #### Enhanced Existing Hooks
 71 | 
 72 | - **`useGunState`** now returns `{ fields, put, remove, error, isLoading, isConnected }`
 73 | - **`useGunCollectionState`** now returns `{ collection, items, addToSet, updateInSet, removeFromSet, error, isLoading, count }`
 74 | - **`useGunKeyAuth`** now returns `[namespace, isLoggedIn, error]` with proper error handling
 75 | - **`useGunOnNodeUpdated`** has improved memory management and error handling
 76 | 
 77 | #### Developer Experience
 78 | 
 79 | - **Comprehensive development warnings** for configuration issues
 80 | - **Better debugging capabilities** with timestamped logs and context
 81 | - **Improved error messages** with specific context about where errors occurred
 82 | - **Type-safe operations** with IDE autocomplete and error detection
 83 | - **Integrated authentication system** with automatic key storage and retrieval
 84 | - **Storage abstraction** for flexible key persistence (localStorage, AsyncStorage, etc.)
 85 | 
 86 | ### Changed
 87 | 
 88 | #### Breaking Changes
 89 | 
 90 | - **Hook return types** now include error and loading states
 91 | - **`useGunKeyAuth`** now returns a tuple with error as third element
 92 | - **Collection hooks** now provide both `collection` (Map) and `items` (Array)
 93 | - **Error handling** is now explicit rather than silent failures
 94 | 
 95 | #### API Improvements
 96 | 
 97 | - **More intuitive return objects** with consistent naming
 98 | - **Better function signatures** with proper TypeScript constraints
 99 | - **Enhanced validation** for all user inputs
100 | - **Consistent error reporting** across all hooks
101 | 
102 | ### Fixed
103 | 
104 | #### Critical Fixes
105 | 
106 | - **Memory leaks** in listener cleanup (useGunOnNodeUpdated)
107 | - **Race conditions** in mount/unmount scenarios
108 | - **Silent failures** in async operations
109 | - **Improper error propagation** from GunDB callbacks
110 | 
111 | #### Type Safety Fixes
112 | 
113 | - **Removed extensive use of `any` types** (reduced by ~90%)
114 | - **Fixed generic type constraints** for better IDE support
115 | - **Proper nullable types** for optional parameters
116 | - **Enhanced type inference** for hook return values
117 | 
118 | ### Infrastructure
119 | 
120 | #### Development Tools
121 | 
122 | - **Enhanced debugging utilities** for development workflow
123 | - **Better error boundaries** and error handling patterns
124 | - **Improved development warnings** system
125 | - **Type-safe development helpers**
126 | 
127 | #### Build & Distribution
128 | 
129 | - **Updated package metadata** with new keywords and description
130 | - **Better TypeScript integration** with proper type exports
131 | - **Enhanced module resolution** for both React and Preact
132 | 
133 | ### Documentation
134 | 
135 | #### New Documentation and Updated Examples
136 | 
137 | - **Migration documentation**
138 | - **TypeScript examples** in all documentation
139 | - **Error handling patterns** and best practices
140 | - **Type-safe examples** with proper error handling
141 | - **Real-world usage patterns** with context providers
142 | - **Performance optimization examples**
143 | - **Debugging and development workflows**
144 | 
145 | ### Migration Guide
146 | 
147 | #### From v0.9.x to v1.0.0
148 | 
149 | For detailed migration instructions and compatibility information, see the detailed documentation for each hook.
150 | 
151 | ### Performance Improvements
152 | 
153 | - **Reduced unnecessary re-renders** through better memoization and dependency management
154 | - **Fixed memory leaks** in listener cleanup and component unmounting
155 | - **Eliminated uncleaned timeout handlers** in continuous testing scenarios
156 | - **Improved bundle size** with better tree shaking
157 | 
158 | ### Development Experience
159 | 
160 | - **Significantly reduced common development errors** through TypeScript definitions
161 | - **Enhanced IDE support** with proper TypeScript definitions
162 | - **Better debugging capabilities** with contextual logging
163 | - **Comprehensive error messages** with actionable information
164 | 
165 | ---
166 | 
167 | ## [0.9.8] - Previous Release
168 | 
169 | ### Features
170 | 
171 | - Basic GunDB React hooks implementation
172 | - Support for React and Preact
173 | - Encryption/decryption utilities
174 | - Real-time updates with debouncing
175 | - Collection state management
176 | 
177 | ### Known Issues (Fixed in v1.0.0)
178 | 
179 | - Memory leaks in listener cleanup
180 | - Limited TypeScript support
181 | - Silent error failures
182 | - Missing development tools
183 | - Performance optimization opportunities
184 | 
185 | ---
186 | 
187 | ## Migration Support
188 | 
189 | For detailed migration instructions and compatibility information, see the detailed documentation for each hook.
190 | 


--------------------------------------------------------------------------------
/dist/index.d.ts:
--------------------------------------------------------------------------------
  1 | import React from 'react';
  2 | export interface IGunChainReference<T = any> {
  3 |     get(key: string): IGunChainReference<T>;
  4 |     put(data: T, callback?: (ack: {
  5 |         err?: string;
  6 |         ok?: any;
  7 |     }) => void): IGunChainReference<T>;
  8 |     on(callback: (data: T, key: string, message?: any, event?: any) => void): () => void;
  9 |     once(callback: (data: T, key: string) => void): void;
 10 |     set(data: T, callback?: (ack: {
 11 |         err?: string;
 12 |         ok?: any;
 13 |     }) => void): IGunChainReference<T>;
 14 |     map(): IGunChainReference<T>;
 15 |     open?(callback: (data: T, key: string, message?: any, event?: any) => void): void;
 16 |     user(soul?: string): IGunUserReference;
 17 |     off(): void;
 18 |     toString(): string;
 19 | }
 20 | export interface IGunUserReference extends IGunChainReference {
 21 |     is: KeyPair | null;
 22 |     auth(keypair: KeyPair, callback?: (ack: any) => void): void;
 23 |     create(keypair: KeyPair, callback?: (ack: any) => void): void;
 24 |     leave(): void;
 25 | }
 26 | export interface GunError {
 27 |     err: string;
 28 |     code?: string | number;
 29 |     context?: string;
 30 | }
 31 | export type ValidGunData = string | number | boolean | object | null;
 32 | export type GunStatic = any;
 33 | export type GunRef = IGunChainReference | null;
 34 | export type NamespacedRef = IGunUserReference;
 35 | export type KeyPair = {
 36 |     pub: string;
 37 |     priv: string;
 38 |     epub: string;
 39 |     epriv: string;
 40 | };
 41 | export type Storage = {
 42 |     getItem: (key: string) => any;
 43 |     setItem: (key: string, data: string) => any;
 44 |     removeItem: (key: string) => any;
 45 | };
 46 | export type AuthContextType = {
 47 |     gun: IGunChainReference;
 48 |     user: IGunUserReference;
 49 |     login: (keys?: undefined | string | KeyPair) => void;
 50 |     logout: (onLoggedOut?: () => void) => void;
 51 |     sea: any;
 52 |     appKeys: undefined | string | KeyPair;
 53 |     isLoggedIn: boolean;
 54 |     newGunInstance: (opts?: GunOptions) => IGunChainReference;
 55 | };
 56 | export type AuthProviderOpts = {
 57 |     Gun: any;
 58 |     sea: any;
 59 |     keyFieldName?: string;
 60 |     storage: Storage;
 61 |     gunOpts: GunOptions;
 62 |     children: React.ReactNode;
 63 | };
 64 | export type Options = {
 65 |     appKeys?: undefined | string | KeyPair;
 66 |     sea?: any;
 67 |     interval?: number;
 68 |     useOpen?: boolean;
 69 | };
 70 | export type NodeData<T extends ValidGunData> = T & {
 71 |     readonly nodeID: string;
 72 |     readonly _?: {
 73 |         '#': string;
 74 |         '>': Record<string, number>;
 75 |     };
 76 | };
 77 | export type NodeT<T> = T & {
 78 |     nodeID: string;
 79 |     [key: string]: any;
 80 | };
 81 | export type ActionType<T> = {
 82 |     type: 'add';
 83 |     data: NodeT<T> | NodeT<T>[];
 84 | } | {
 85 |     type: 'update';
 86 |     data: NodeT<T>;
 87 | } | {
 88 |     type: 'remove';
 89 |     data: {
 90 |         nodeID: string;
 91 |     };
 92 | };
 93 | export type UpdateType = {
 94 |     id: string;
 95 |     data: any;
 96 | };
 97 | export interface GunOptions extends Partial<{
 98 |     file: string;
 99 |     web: any;
100 |     s3: {
101 |         key: any;
102 |         secret: any;
103 |         bucket: any;
104 |     };
105 |     peers: string[] | Record<string, {}>;
106 |     radisk: boolean;
107 |     localStorage: boolean;
108 |     uuid(): string;
109 |     [key: string]: any;
110 | }> {
111 | }
112 | export interface CollectionState<T> {
113 |     collection: Map<string, T>;
114 |     sorted?: T[];
115 |     infiniteScrolling?: {
116 |         isFetching: boolean;
117 |         lastFetched: string;
118 |         reverse: boolean;
119 |     };
120 | }
121 | export interface UseGunStateReturn<T> {
122 |     fields: T;
123 |     put: (data: Partial<T>) => Promise<void>;
124 |     remove: (field: string) => Promise<void>;
125 |     error: GunError | null;
126 |     isLoading: boolean;
127 |     isConnected: boolean;
128 | }
129 | export interface UseGunCollectionReturn<T> {
130 |     collection: Map<string, NodeT<T>>;
131 |     items: NodeT<T>[];
132 |     addToSet: (data: T, nodeID?: string) => Promise<void>;
133 |     updateInSet: (nodeID: string, data: Partial<T>) => Promise<void>;
134 |     removeFromSet: (nodeID: string) => Promise<void>;
135 |     error: GunError | null;
136 |     isLoading: boolean;
137 |     count: number;
138 | }
139 | export interface PaginationOptions<T> extends Options {
140 |     pageSize?: number;
141 |     currentPage?: number;
142 |     sortBy?: keyof T | ((a: NodeT<T>, b: NodeT<T>) => number);
143 |     sortOrder?: 'asc' | 'desc';
144 |     filter?: (item: NodeT<T>) => boolean;
145 |     preloadPages?: number;
146 | }
147 | export interface UsePaginatedCollectionReturn<T> extends UseGunCollectionReturn<T> {
148 |     currentPage: number;
149 |     totalPages: number;
150 |     hasNextPage: boolean;
151 |     hasPrevPage: boolean;
152 |     pageSize: number;
153 |     nextPage: () => void;
154 |     prevPage: () => void;
155 |     goToPage: (page: number) => void;
156 |     setPageSize: (size: number) => void;
157 |     currentPageItems: NodeT<T>[];
158 |     currentPageCount: number;
159 |     isLoadingPage: boolean;
160 |     preloadedPages: Set<number>;
161 | }
162 | export declare const encryptData: (data: any, keys: undefined | string | KeyPair, sea: any) => Promise<any>;
163 | export declare const decryptData: (data: any, keys: undefined | string | KeyPair, sea: any) => Promise<any>;
164 | export declare const debouncedUpdates: (dispatcher: any, type?: string, timeout?: number) => {
165 |     (update: UpdateType): () => void;
166 |     cleanup(): void;
167 | };
168 | export declare const useIsMounted: () => any;
169 | export declare const nodeReducer: <T>(state: NodeT<T>, { data, type }: ActionType<T>) => T;
170 | export declare const collectionReducer: <T>(state: CollectionState<T>, { data, type }: ActionType<T>) => CollectionState<T>;
171 | export declare const useSafeReducer: <T>(reducer: any, initialState: T) => [T, Function];
172 | export declare const useGun: (Gun: GunStatic, opts: GunOptions) => any;
173 | export declare const useGunNamespace: (gun: GunRef, soul?: string) => any;
174 | export declare const useGunKeyAuth: (gun: GunRef, keys: KeyPair, triggerAuth?: boolean) => readonly [any, any, any];
175 | export declare const useGunKeys: (sea: any, existingKeys?: KeyPair | undefined | null) => any;
176 | export declare const useGunOnNodeUpdated: <T>(ref: GunRef, opts: Options | undefined, cb: (data: T, nodeID: string) => void, cleanup?: () => void) => void;
177 | export declare const useGunState: <T>(ref: GunRef, opts?: Options) => UseGunStateReturn<T>;
178 | export declare const useGunCollectionState: <T extends Record<string, any>>(ref: GunRef, opts?: Options) => UseGunCollectionReturn<T>;
179 | export declare const useGunCollectionStatePaginated: <T extends Record<string, any>>(ref: GunRef, paginationOpts?: PaginationOptions<T>) => UsePaginatedCollectionReturn<T>;
180 | export declare const AuthContext: any;
181 | export declare const AuthProvider: React.FC<AuthProviderOpts>;
182 | export declare const useAuth: () => AuthContextType;
183 | export declare const GunContext: any;
184 | export declare const GunProvider: React.FC<{
185 |     gun: GunStatic;
186 |     options: GunOptions;
187 |     children: React.ReactNode;
188 | }>;
189 | export declare const useGunContext: () => IGunChainReference;
190 | export declare const useGunDebug: (ref: IGunChainReference | null, label: string, enabled?: boolean) => void;
191 | export declare const useGunConnection: (ref: IGunChainReference) => {
192 |     isConnected: boolean;
193 |     lastSeen: Date | null;
194 |     error: GunError | null;
195 | };
196 | 


--------------------------------------------------------------------------------
/docs/useAuth.md:
--------------------------------------------------------------------------------
  1 | # useAuth
  2 | 
  3 | A comprehensive authentication hook for GunDB applications that provides automatic key generation, storage management, and authentication state tracking.
  4 | 
  5 | ## Overview
  6 | 
  7 | The `useAuth` hook provides a complete authentication solution for GunDB applications, managing user keys, authentication state, and secure storage automatically. It integrates seamlessly with the `AuthProvider` component to deliver a robust authentication system.
  8 | 
  9 | ## API Reference
 10 | 
 11 | ### Signature
 12 | 
 13 | ```typescript
 14 | useAuth(): AuthContextType
 15 | ```
 16 | 
 17 | ### Return Type
 18 | 
 19 | ```typescript
 20 | interface AuthContextType {
 21 |   gun: IGunChainReference; // Gun instance
 22 |   user: IGunUserReference; // Authenticated user reference
 23 |   login: (keys?: KeyPair | string) => void; // Login function
 24 |   logout: (onLoggedOut?: () => void) => void; // Logout function
 25 |   sea: any; // SEA instance
 26 |   appKeys: KeyPair | string | undefined; // Current keys
 27 |   isLoggedIn: boolean; // Authentication status
 28 |   newGunInstance: (opts?: GunOptions) => IGunChainReference; // Create new Gun instance
 29 | }
 30 | ```
 31 | 
 32 | ## Basic Usage
 33 | 
 34 | ```typescript
 35 | import { AuthProvider, useAuth } from '@altrx/gundb-react-hooks';
 36 | import Gun from 'gun';
 37 | import 'gun/sea';
 38 | 
 39 | // Wrap your app with AuthProvider
 40 | function App() {
 41 |   return (
 42 |     <AuthProvider
 43 |       Gun={Gun}
 44 |       sea={Gun.SEA}
 45 |       storage={localStorage}
 46 |       gunOpts={{ peers: ['http://localhost:8765/gun'] }}
 47 |     >
 48 |       <AuthenticatedApp />
 49 |     </AuthProvider>
 50 |   );
 51 | }
 52 | 
 53 | // Use authentication in components
 54 | function AuthenticatedApp() {
 55 |   const {
 56 |     user,
 57 |     login,
 58 |     logout,
 59 |     isLoggedIn,
 60 |     appKeys,
 61 |     gun
 62 |   } = useAuth();
 63 | 
 64 |   return (
 65 |     <div>
 66 |       {isLoggedIn ? (
 67 |         <div>
 68 |           <p>Welcome! You are authenticated.</p>
 69 |           <p>Your public key: {appKeys?.pub}</p>
 70 |           <button onClick={() => logout()}>Logout</button>
 71 |         </div>
 72 |       ) : (
 73 |         <div>
 74 |           <p>Please log in</p>
 75 |           <button onClick={() => login()}>Login with new keys</button>
 76 |         </div>
 77 |       )}
 78 |     </div>
 79 |   );
 80 | }
 81 | ```
 82 | 
 83 | ## Advanced Usage
 84 | 
 85 | ### Custom Storage Implementation
 86 | 
 87 | ```typescript
 88 | // For React Native with AsyncStorage
 89 | import AsyncStorage from '@react-native-async-storage/async-storage';
 90 | 
 91 | const asyncStorage = {
 92 |   getItem: async (key: string) => {
 93 |     const value = await AsyncStorage.getItem(key);
 94 |     return value;
 95 |   },
 96 |   setItem: async (key: string, data: string) => {
 97 |     await AsyncStorage.setItem(key, data);
 98 |   },
 99 |   removeItem: async (key: string) => {
100 |     await AsyncStorage.removeItem(key);
101 |   }
102 | };
103 | 
104 | <AuthProvider storage={asyncStorage} ... />
105 | ```
106 | 
107 | ### Login with Existing Keys
108 | 
109 | ```typescript
110 | function LoginForm() {
111 |   const { login } = useAuth();
112 |   const [keyInput, setKeyInput] = useState('');
113 | 
114 |   const handleLogin = () => {
115 |     try {
116 |       const keys = JSON.parse(keyInput);
117 |       login(keys);
118 |     } catch (error) {
119 |       console.error('Invalid key format:', error);
120 |     }
121 |   };
122 | 
123 |   return (
124 |     <div>
125 |       <textarea
126 |         value={keyInput}
127 |         onChange={(e) => setKeyInput(e.target.value)}
128 |         placeholder="Paste your keys here..."
129 |       />
130 |       <button onClick={handleLogin}>Login</button>
131 |     </div>
132 |   );
133 | }
134 | ```
135 | 
136 | ### Key Export/Import
137 | 
138 | ```typescript
139 | function KeyManagement() {
140 |   const { appKeys, isLoggedIn } = useAuth();
141 | 
142 |   const exportKeys = () => {
143 |     if (appKeys) {
144 |       const keyString = JSON.stringify(appKeys, null, 2);
145 |       navigator.clipboard.writeText(keyString);
146 |       alert('Keys copied to clipboard');
147 |     }
148 |   };
149 | 
150 |   return (
151 |     <div>
152 |       {isLoggedIn && (
153 |         <button onClick={exportKeys}>
154 |           Export Keys
155 |         </button>
156 |       )}
157 |     </div>
158 |   );
159 | }
160 | ```
161 | 
162 | ### Logout with Callback
163 | 
164 | ```typescript
165 | function LogoutButton() {
166 |   const { logout } = useAuth();
167 | 
168 |   const handleLogout = () => {
169 |     logout(() => {
170 |       // Cleanup after logout
171 |       console.log('User logged out successfully');
172 |       // Redirect or update UI
173 |       window.location.href = '/login';
174 |     });
175 |   };
176 | 
177 |   return <button onClick={handleLogout}>Logout</button>;
178 | }
179 | ```
180 | 
181 | ## Integration with Other Hooks
182 | 
183 | ### Using with useGunState
184 | 
185 | ```typescript
186 | function UserProfile() {
187 |   const { user, isLoggedIn } = useAuth();
188 |   const { fields, put, error } = useGunState(
189 |     user?.get('profile'),
190 |     { appKeys: user?.is }
191 |   );
192 | 
193 |   if (!isLoggedIn) return <div>Please log in</div>;
194 | 
195 |   return (
196 |     <div>
197 |       <input
198 |         value={fields.name || ''}
199 |         onChange={(e) => put({ name: e.target.value })}
200 |       />
201 |       {error && <div>Error: {error.err}</div>}
202 |     </div>
203 |   );
204 | }
205 | ```
206 | 
207 | ### Using with useGunCollectionState
208 | 
209 | ```typescript
210 | function UserPosts() {
211 |   const { user, isLoggedIn } = useAuth();
212 |   const { items, addToSet, error } = useGunCollectionState(
213 |     user?.get('posts'),
214 |     { appKeys: user?.is }
215 |   );
216 | 
217 |   if (!isLoggedIn) return <div>Please log in</div>;
218 | 
219 |   return (
220 |     <div>
221 |       {items.map(post => (
222 |         <div key={post.nodeID}>{post.title}</div>
223 |       ))}
224 |       <button onClick={() => addToSet({ title: 'New Post' })}>
225 |         Add Post
226 |       </button>
227 |       {error && <div>Error: {error.err}</div>}
228 |     </div>
229 |   );
230 | }
231 | ```
232 | 
233 | ## Error Handling
234 | 
235 | The authentication system includes comprehensive error handling:
236 | 
237 | ```typescript
238 | function AuthStatus() {
239 |   const { isLoggedIn, login } = useAuth();
240 | 
241 |   const handleLogin = async () => {
242 |     try {
243 |       await login();
244 |     } catch (error) {
245 |       console.error('Login failed:', error);
246 |       // Handle authentication errors
247 |     }
248 |   };
249 | 
250 |   return (
251 |     <div>
252 |       <p>Status: {isLoggedIn ? 'Authenticated' : 'Not authenticated'}</p>
253 |       <button onClick={handleLogin}>Login</button>
254 |     </div>
255 |   );
256 | }
257 | ```
258 | 
259 | ## Migration from v0.9.x
260 | 
261 | ### Before (v0.9.x)
262 | 
263 | ```typescript
264 | // Manual authentication management
265 | const [keys, setKeys] = useState(null);
266 | const [user, setUser] = useState(null);
267 | const [isLoggedIn, setIsLoggedIn] = useState(false);
268 | 
269 | // Manual key storage
270 | useEffect(() => {
271 |   const storedKeys = localStorage.getItem('keys');
272 |   if (storedKeys) {
273 |     setKeys(JSON.parse(storedKeys));
274 |   }
275 | }, []);
276 | ```
277 | 
278 | ### After (v1.0.0)
279 | 
280 | ```typescript
281 | // Automatic authentication with AuthProvider
282 | function App() {
283 |   return (
284 |     <AuthProvider Gun={Gun} sea={Gun.SEA} storage={localStorage} gunOpts={opts}>
285 |       <AuthenticatedApp />
286 |     </AuthProvider>
287 |   );
288 | }
289 | 
290 | // Simple hook usage
291 | const { user, login, logout, isLoggedIn, appKeys } = useAuth();
292 | ```
293 | 
294 | ## Best Practices
295 | 
296 | 1. **Always wrap your app** with `AuthProvider` at the root level
297 | 2. **Use meaningful storage keys** when deploying multiple apps
298 | 3. **Handle storage failures** gracefully in your storage implementation
299 | 4. **Secure key storage** in production environments
300 | 5. **Validate imported keys** before using them
301 | 6. **Provide clear user feedback** during authentication processes
302 | 
303 | ## TypeScript Support
304 | 
305 | All authentication features are fully typed:
306 | 
307 | ```typescript
308 | import type {
309 |   KeyPair,
310 |   AuthContextType,
311 |   Storage,
312 | } from '@altrx/gundb-react-hooks';
313 | 
314 | const customStorage: Storage = {
315 |   getItem: (key: string) => localStorage.getItem(key),
316 |   setItem: (key: string, data: string) => localStorage.setItem(key, data),
317 |   removeItem: (key: string) => localStorage.removeItem(key),
318 | };
319 | ```
320 | 
321 | ## Common Patterns
322 | 
323 | ### Protected Routes
324 | 
325 | ```typescript
326 | function ProtectedRoute({ children }: { children: React.ReactNode }) {
327 |   const { isLoggedIn } = useAuth();
328 | 
329 |   if (!isLoggedIn) {
330 |     return <LoginForm />;
331 |   }
332 | 
333 |   return <>{children}</>;
334 | }
335 | ```
336 | 
337 | ### Automatic Key Backup
338 | 
339 | ```typescript
340 | function AutoBackup() {
341 |   const { appKeys, isLoggedIn } = useAuth();
342 | 
343 |   useEffect(() => {
344 |     if (isLoggedIn && appKeys) {
345 |       // Automatically backup keys to secure storage
346 |       backupKeysToSecureStorage(appKeys);
347 |     }
348 |   }, [isLoggedIn, appKeys]);
349 | 
350 |   return null;
351 | }
352 | ```
353 | 


--------------------------------------------------------------------------------
/preact/dist/gundb-react-hooks.modern.js:
--------------------------------------------------------------------------------
  1 | import { useRef, useEffect, useReducer, useState } from 'preact/hooks';
  2 | 
  3 | function _extends() {
  4 |   _extends = Object.assign || function (target) {
  5 |     for (var i = 1; i < arguments.length; i++) {
  6 |       var source = arguments[i];
  7 | 
  8 |       for (var key in source) {
  9 |         if (Object.prototype.hasOwnProperty.call(source, key)) {
 10 |           target[key] = source[key];
 11 |         }
 12 |       }
 13 |     }
 14 | 
 15 |     return target;
 16 |   };
 17 | 
 18 |   return _extends.apply(this, arguments);
 19 | }
 20 | 
 21 | const encryptData = async (data, keys, sea) => {
 22 |   return keys && sea ? sea.encrypt(data, keys) : Promise.resolve(data);
 23 | };
 24 | const decryptData = async (data, keys, sea) => {
 25 |   return keys && sea ? sea.decrypt(data, keys) : Promise.resolve(data);
 26 | };
 27 | const debouncedUpdates = (dispatcher, type = 'object', timeout = 100) => {
 28 |   let updates = [];
 29 |   let handler;
 30 |   return update => {
 31 |     updates.push(update);
 32 | 
 33 |     if (!handler) {
 34 |       handler = setTimeout(() => {
 35 |         let newStateSlice = updates.reduce((previousState, {
 36 |           id,
 37 |           data
 38 |         }) => {
 39 |           if (type === 'object') {
 40 |             previousState[id] = data;
 41 |           } else {
 42 |             previousState.set(id, data);
 43 |           }
 44 | 
 45 |           return previousState;
 46 |         }, type === 'object' ? {} : new Map());
 47 |         dispatcher(newStateSlice);
 48 |         updates = [];
 49 |         handler = null;
 50 |       }, timeout);
 51 |     }
 52 | 
 53 |     return () => {
 54 |       clearTimeout(handler);
 55 |       updates = [];
 56 |       handler = null;
 57 |     };
 58 |   };
 59 | };
 60 | const useIsMounted = () => {
 61 |   const isMounted = useRef(false);
 62 |   useEffect(() => {
 63 |     isMounted.current = true;
 64 |     return () => {
 65 |       isMounted.current = false;
 66 |     };
 67 |   }, []);
 68 |   return isMounted;
 69 | };
 70 | const nodeReducer = (state, {
 71 |   data,
 72 |   type
 73 | }) => {
 74 |   switch (type) {
 75 |     case 'add':
 76 |       return _extends({}, state, data);
 77 | 
 78 |     case 'remove':
 79 |       delete state[data.nodeID];
 80 |       return _extends({}, state);
 81 | 
 82 |     default:
 83 |       throw new Error();
 84 |   }
 85 | };
 86 | const collectionReducer = (state, {
 87 |   data,
 88 |   type
 89 | }) => {
 90 |   var _state$collection2, _state$collection3;
 91 | 
 92 |   switch (type) {
 93 |     case 'add':
 94 |       data.forEach(data => {
 95 |         var _state$collection;
 96 | 
 97 |         (_state$collection = state.collection) == null ? void 0 : _state$collection.set(data.nodeID, data);
 98 |       });
 99 |       return _extends({}, state, {
100 |         collection: state.collection
101 |       });
102 | 
103 |     case 'update':
104 |       (_state$collection2 = state.collection) == null ? void 0 : _state$collection2.set(data.nodeID, data);
105 |       return _extends({}, state, {
106 |         collection: state.collection
107 |       });
108 | 
109 |     case 'remove':
110 |       (_state$collection3 = state.collection) == null ? void 0 : _state$collection3.delete(data.nodeID);
111 |       return _extends({}, state, {
112 |         collection: state.collection
113 |       });
114 | 
115 |     default:
116 |       throw new Error();
117 |   }
118 | };
119 | const useSafeReducer = (reducer, initialState) => {
120 |   const [state, dispatch] = useReducer(reducer, initialState);
121 |   const isMounted = useIsMounted();
122 | 
123 |   function safeDispatch(args) {
124 |     if (isMounted.current) {
125 |       dispatch(args);
126 |     }
127 |   }
128 | 
129 |   return [state, safeDispatch];
130 | };
131 | const useGun = (Gun, opts) => {
132 |   const [gun, setGun] = useState(Gun(_extends({}, opts)));
133 |   useEffect(() => {
134 |     if (opts) {
135 |       setGun(Gun(_extends({}, opts)));
136 |     }
137 |   }, [Gun, opts]);
138 |   return gun;
139 | };
140 | const useGunNamespace = (gun, soul) => {
141 |   const [namespace, setNamespace] = useState(soul ? gun.user(soul) : gun.user());
142 |   useEffect(() => {
143 |     if (gun && !namespace) {
144 |       setNamespace(soul ? gun.user(soul) : gun.user());
145 |     }
146 |   }, [namespace, gun, soul]);
147 |   return namespace;
148 | };
149 | const useGunKeyAuth = (gun, keys, triggerAuth = true) => {
150 |   // Will attempt to perform a login (when triggerAuth is set to true),
151 |   // or, if false, returns a namespaced gun node
152 |   const namespacedGraph = useGunNamespace(gun);
153 |   const [isLoggedIn, setIsLoggedIn] = useState(false);
154 |   gun.on('auth', () => {
155 |     setIsLoggedIn(true);
156 |   });
157 |   useEffect(() => {
158 |     if (namespacedGraph && !namespacedGraph.is && keys && triggerAuth) {
159 |       namespacedGraph.auth(keys);
160 |     }
161 |   }, [triggerAuth, namespacedGraph, keys]);
162 |   return [namespacedGraph, isLoggedIn];
163 | };
164 | const useGunKeys = (sea, existingKeys) => {
165 |   const [newKeys, setNewKeys] = useState(existingKeys);
166 |   useEffect(() => {
167 |     async function getKeySet() {
168 |       const pair = await sea.pair();
169 |       setNewKeys(pair);
170 |     }
171 | 
172 |     if (!newKeys && !existingKeys) {
173 |       getKeySet();
174 |     }
175 | 
176 |     if (existingKeys) {
177 |       setNewKeys(existingKeys);
178 |     }
179 |   }, [existingKeys, newKeys, sea]);
180 |   return newKeys;
181 | };
182 | const useGunOnNodeUpdated = (ref, opts = {
183 |   appKeys: '',
184 |   sea: null,
185 |   useOpen: false
186 | }, cb, cleanup) => {
187 |   const {
188 |     appKeys,
189 |     sea,
190 |     useOpen
191 |   } = opts;
192 |   const handler = useRef(null);
193 |   const isMounted = useIsMounted();
194 |   useEffect(() => {
195 |     if (isMounted.current) {
196 |       const gunCb = async (encryptedField, nodeID, message, event) => {
197 |         let decryptedField = await decryptData(encryptedField, appKeys, sea);
198 |         cb(decryptedField, nodeID);
199 | 
200 |         if (!handler.current) {
201 |           handler.current = event;
202 |         }
203 |       };
204 | 
205 |       if (useOpen) {
206 |         if (!ref.open) {
207 |           throw new Error('Please include gun/lib/open.');
208 |         } else {
209 |           ref.open(gunCb);
210 |         }
211 |       } else {
212 |         ref.on(gunCb);
213 |       }
214 |     }
215 | 
216 |     return () => {
217 |       if (handler.current) {
218 |         //cleanup gun .on listener
219 |         handler.current.off();
220 |       }
221 | 
222 |       if (cleanup) {
223 |         cleanup();
224 |       }
225 |     };
226 |   }, [ref]);
227 | };
228 | const useGunState = (ref, opts = {
229 |   appKeys: '',
230 |   sea: null,
231 |   interval: 100,
232 |   useOpen: false
233 | }) => {
234 |   const {
235 |     appKeys,
236 |     sea,
237 |     interval = 100
238 |   } = opts;
239 |   const [fields, dispatch] = useSafeReducer(nodeReducer, {});
240 |   const debouncedHandlers = [];
241 |   const updater = debouncedUpdates(data => {
242 |     dispatch({
243 |       type: 'add',
244 |       data
245 |     });
246 |   }, 'object', interval);
247 |   useGunOnNodeUpdated(ref, opts, item => {
248 |     Object.keys(item).forEach(key => {
249 |       let cleanFn = updater({
250 |         id: key,
251 |         data: item[key]
252 |       });
253 |       debouncedHandlers.push(cleanFn);
254 |     });
255 |   }, () => {
256 |     if (debouncedHandlers.length) {
257 |       //cleanup timeouts
258 |       debouncedHandlers.forEach(c => c());
259 |     }
260 |   }); // Working with root node fields
261 | 
262 |   const put = async data => {
263 |     let encryptedData = await encryptData(data, appKeys, sea);
264 |     await new Promise((resolve, reject) => ref.put(encryptedData, ack => ack.err ? reject(ack.err) : resolve(data)));
265 |   };
266 | 
267 |   const remove = async field => {
268 |     await new Promise((resolve, reject) => ref.put(null, ack => ack.err ? reject(ack.err) : resolve(field)));
269 |     dispatch({
270 |       type: 'remove',
271 |       data: {
272 |         nodeID: field
273 |       }
274 |     });
275 |   };
276 | 
277 |   return {
278 |     fields,
279 |     put,
280 |     remove
281 |   };
282 | };
283 | const useGunCollectionState = (ref, opts = {
284 |   appKeys: '',
285 |   sea: null,
286 |   interval: 100,
287 |   useOpen: false
288 | }) => {
289 |   const {
290 |     appKeys,
291 |     sea,
292 |     interval = 100
293 |   } = opts;
294 |   const [{
295 |     collection
296 |   }, dispatch] = useSafeReducer(collectionReducer, {
297 |     collection: new Map()
298 |   });
299 |   const debouncedHandlers = [];
300 |   const updater = debouncedUpdates(data => {
301 |     dispatch({
302 |       type: 'add',
303 |       data
304 |     });
305 |   }, 'map', interval);
306 |   useGunOnNodeUpdated(ref.map(), opts, (item, nodeID) => {
307 |     if (item) {
308 |       let cleanFn = updater({
309 |         id: nodeID,
310 |         data: _extends({}, item, {
311 |           nodeID
312 |         })
313 |       });
314 |       debouncedHandlers.push(cleanFn);
315 |     }
316 |   }, () => {
317 |     if (debouncedHandlers.length) {
318 |       //cleanup timeouts
319 |       debouncedHandlers.forEach(c => c());
320 |     }
321 |   }); // Working with Sets
322 | 
323 |   const updateInSet = async (nodeID, data) => {
324 |     let encryptedData = await encryptData(data, appKeys, sea);
325 |     await new Promise((resolve, reject) => ref.get(nodeID).put(encryptedData, ack => ack.err ? reject(ack.err) : resolve(data)));
326 |     dispatch({
327 |       type: 'update',
328 |       data: _extends({
329 |         nodeID
330 |       }, data)
331 |     });
332 |   };
333 | 
334 |   const addToSet = async (data, nodeID) => {
335 |     let encryptedData = await encryptData(data, appKeys, sea);
336 | 
337 |     if (!nodeID) {
338 |       await new Promise((resolve, reject) => ref.set(encryptedData, ack => ack.err ? reject(ack.err) : resolve(data)));
339 |     } else {
340 |       await new Promise((resolve, reject) => ref.get(nodeID).put(encryptedData, ack => ack.err ? reject(ack.err) : resolve(data)));
341 |     }
342 |   };
343 | 
344 |   const removeFromSet = async nodeID => {
345 |     await new Promise((resolve, reject) => ref.get(nodeID).put(null, ack => ack.err ? reject(ack.err) : resolve(nodeID)));
346 |   };
347 | 
348 |   return {
349 |     collection,
350 |     addToSet,
351 |     updateInSet,
352 |     removeFromSet
353 |   };
354 | };
355 | 
356 | export { collectionReducer, debouncedUpdates, decryptData, encryptData, nodeReducer, useGun, useGunCollectionState, useGunKeyAuth, useGunKeys, useGunNamespace, useGunOnNodeUpdated, useGunState, useIsMounted, useSafeReducer };
357 | //# sourceMappingURL=gundb-react-hooks.modern.js.map
358 | 


--------------------------------------------------------------------------------
/docs/useGunState.md:
--------------------------------------------------------------------------------
  1 | # useGunState
  2 | 
  3 | A hook that provides access to a Gun node with comprehensive error handling, loading states, and TypeScript support.
  4 | 
  5 | ## API Reference
  6 | 
  7 | ### Signature
  8 | 
  9 | ```typescript
 10 | useGunState<T>(ref: GunRef, opts?: Options): UseGunStateReturn<T>
 11 | ```
 12 | 
 13 | ### Return Type
 14 | 
 15 | ```typescript
 16 | interface UseGunStateReturn<T> {
 17 |   fields: T;                                    // Current state data
 18 |   put: (data: Partial<T>) => Promise<void>;     // Update operation
 19 |   remove: (field: string) => Promise<void>;    // Remove field
 20 |   error: GunError | null;                      // Error state
 21 |   isLoading: boolean;                          // Loading state
 22 |   isConnected: boolean;                        // Connection status
 23 | }
 24 | ```
 25 | 
 26 | ### Error Type
 27 | 
 28 | ```typescript
 29 | interface GunError {
 30 |   err: string;           // Error message
 31 |   code?: string | number; // Error code (if available)
 32 |   context?: string;      // Context where error occurred
 33 | }
 34 | ```
 35 | 
 36 | ## Basic Usage
 37 | 
 38 | ### Simple State Management
 39 | 
 40 | ```typescript
 41 | import React from 'react';
 42 | import { useGun, useGunState } from '@altrx/gundb-react-hooks';
 43 | import Gun from 'gun';
 44 | 
 45 | interface UserProfile {
 46 |   name: string;
 47 |   email: string;
 48 |   avatar?: string;
 49 | }
 50 | 
 51 | export const UserProfileComponent: React.FC = () => {
 52 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
 53 |   
 54 |   const { 
 55 |     fields: profile, 
 56 |     put, 
 57 |     remove,
 58 |     error, 
 59 |     isLoading, 
 60 |     isConnected 
 61 |   } = useGunState<UserProfile>(gun.get('user').get('profile'));
 62 | 
 63 |   // Handle loading state
 64 |   if (isLoading) {
 65 |     return <div>Loading profile...</div>;
 66 |   }
 67 | 
 68 |   // Handle connection issues
 69 |   if (!isConnected) {
 70 |     return <div>Connecting to Gun network...</div>;
 71 |   }
 72 | 
 73 |   // Handle errors
 74 |   if (error) {
 75 |     return (
 76 |       <div className="error">
 77 |         <h3>Error loading profile</h3>
 78 |         <p>{error.err}</p>
 79 |         {error.context && <small>Context: {error.context}</small>}
 80 |       </div>
 81 |     );
 82 |   }
 83 | 
 84 |   const handleUpdateProfile = async () => {
 85 |     try {
 86 |       await put({
 87 |         name: 'John Doe',
 88 |         email: 'john@example.com'
 89 |       });
 90 |       console.log('Profile updated successfully');
 91 |     } catch (error) {
 92 |       console.error('Failed to update profile:', error);
 93 |     }
 94 |   };
 95 | 
 96 |   const handleRemoveAvatar = async () => {
 97 |     try {
 98 |       await remove('avatar');
 99 |       console.log('Avatar removed');
100 |     } catch (error) {
101 |       console.error('Failed to remove avatar:', error);
102 |     }
103 |   };
104 | 
105 |   return (
106 |     <div>
107 |       <h1>{profile.name || 'Anonymous User'}</h1>
108 |       <p>Email: {profile.email || 'Not set'}</p>
109 |       {profile.avatar && (
110 |         <div>
111 |           <img src={profile.avatar} alt="Avatar" />
112 |           <button onClick={handleRemoveAvatar}>Remove Avatar</button>
113 |         </div>
114 |       )}
115 |       <button onClick={handleUpdateProfile}>Update Profile</button>
116 |     </div>
117 |   );
118 | };
119 | ```
120 | 
121 | ## Advanced Usage
122 | 
123 | ### With Authentication and Encryption
124 | 
125 | ```typescript
126 | import React from 'react';
127 | import { useGun, useGunState, useGunKeyAuth, useGunKeys } from '@altrx/gundb-react-hooks';
128 | import Gun from 'gun';
129 | import SEA from 'gun/sea';
130 | 
131 | interface PrivateNote {
132 |   title: string;
133 |   content: string;
134 |   createdAt: string;
135 | }
136 | 
137 | export const EncryptedNotesApp: React.FC = () => {
138 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
139 |   const appKeys = useGunKeys(SEA);
140 |   const [user, isLoggedIn, authError] = useGunKeyAuth(gun, appKeys!);
141 | 
142 |   // Handle authentication errors
143 |   if (authError) {
144 |     return (
145 |       <div className="auth-error">
146 |         <h3>Authentication Error</h3>
147 |         <p>{authError.err}</p>
148 |       </div>
149 |     );
150 |   }
151 | 
152 |   if (!appKeys) return <div>Generating keys...</div>;
153 |   if (!isLoggedIn) return <div>Logging in...</div>;
154 | 
155 |   return <NotesComponent user={user} appKeys={appKeys} />;
156 | };
157 | 
158 | const NotesComponent: React.FC<{ user: any; appKeys: any }> = ({ user, appKeys }) => {
159 |   const { 
160 |     fields: notes, 
161 |     put, 
162 |     error, 
163 |     isLoading 
164 |   } = useGunState<PrivateNote>(
165 |     user.get('private').get('notes'),
166 |     { appKeys, sea: SEA } // Encrypted storage
167 |   );
168 | 
169 |   const handleSaveNote = async () => {
170 |     try {
171 |       await put({
172 |         title: 'My Secret Note',
173 |         content: 'This content is encrypted!',
174 |         createdAt: new Date().toISOString()
175 |       });
176 |     } catch (error) {
177 |       console.error('Failed to save note:', error);
178 |     }
179 |   };
180 | 
181 |   if (isLoading) return <div>Loading encrypted notes...</div>;
182 |   if (error) return <div>Error: {error.err}</div>;
183 | 
184 |   return (
185 |     <div>
186 |       <h2>Private Notes</h2>
187 |       {notes.title && (
188 |         <div>
189 |           <h3>{notes.title}</h3>
190 |           <p>{notes.content}</p>
191 |           <small>Created: {notes.createdAt}</small>
192 |         </div>
193 |       )}
194 |       <button onClick={handleSaveNote}>Add Encrypted Note</button>
195 |     </div>
196 |   );
197 | };
198 | ```
199 | 
200 | ### With Context Provider
201 | 
202 | ```typescript
203 | import React from 'react';
204 | import { GunProvider, useGunContext, useGunState } from '@altrx/gundb-react-hooks';
205 | import Gun from 'gun';
206 | 
207 | // App with context provider
208 | export const App: React.FC = () => (
209 |   <GunProvider gun={Gun} options={{ peers: ['http://localhost:8765/gun'] }}>
210 |     <UserDashboard />
211 |   </GunProvider>
212 | );
213 | 
214 | // Component using context
215 | const UserDashboard: React.FC = () => {
216 |   const gun = useGunContext();
217 |   
218 |   const { 
219 |     fields: userStats, 
220 |     put: updateStats,
221 |     error,
222 |     isLoading 
223 |   } = useGunState(gun.get('user').get('stats'));
224 | 
225 |   if (error) return <div>Error: {error.err}</div>;
226 |   if (isLoading) return <div>Loading dashboard...</div>;
227 | 
228 |   return (
229 |     <div>
230 |       <h1>User Dashboard</h1>
231 |       <p>Login count: {userStats.loginCount || 0}</p>
232 |       <button onClick={() => updateStats({ 
233 |         loginCount: (userStats.loginCount || 0) + 1,
234 |         lastLogin: new Date().toISOString()
235 |       })}>
236 |         Increment Login Count
237 |       </button>
238 |     </div>
239 |   );
240 | };
241 | ```
242 | 
243 | ## Error Handling Patterns
244 | 
245 | ### Comprehensive Error Component
246 | 
247 | ```typescript
248 | import { GunError } from '@altrx/gundb-react-hooks';
249 | 
250 | const ErrorDisplay: React.FC<{ error: GunError; onRetry?: () => void }> = ({ 
251 |   error, 
252 |   onRetry 
253 | }) => (
254 |   <div className="error-container">
255 |     <h3>Operation Failed</h3>
256 |     <div className="error-details">
257 |       <p><strong>Error:</strong> {error.err}</p>
258 |       {error.context && <p><strong>Context:</strong> {error.context}</p>}
259 |       {error.code && <p><strong>Code:</strong> {error.code}</p>}
260 |     </div>
261 |     {onRetry && (
262 |       <button onClick={onRetry} className="retry-button">
263 |         Try Again
264 |       </button>
265 |     )}
266 |   </div>
267 | );
268 | 
269 | // Usage in component
270 | const MyComponent: React.FC = () => {
271 |   const { fields, put, error } = useGunState(ref);
272 |   
273 |   if (error) {
274 |     return <ErrorDisplay error={error} onRetry={() => window.location.reload()} />;
275 |   }
276 |   
277 |   return <div>{/* Normal component */}</div>;
278 | };
279 | ```
280 | 
281 | ## Migration from v0.9.x
282 | 
283 | ### Before (v0.9.x)
284 | 
285 | ```typescript
286 | const { fields, put, remove } = useGunState(ref);
287 | // No error handling, silent failures
288 | ```
289 | 
290 | ### After (v1.0.0)
291 | 
292 | ```typescript
293 | const { 
294 |   fields, 
295 |   put, 
296 |   remove, 
297 |   error,        // NEW: Explicit error handling
298 |   isLoading,    // NEW: Loading state
299 |   isConnected   // NEW: Connection status
300 | } = useGunState(ref);
301 | 
302 | // Handle errors explicitly
303 | if (error) {
304 |   console.error('Gun operation failed:', error.err);
305 | }
306 | ```
307 | 
308 | ## Development & Debugging
309 | 
310 | ### Debug Hook Integration
311 | 
312 | ```typescript
313 | import { useGunState, useGunDebug } from '@altrx/gundb-react-hooks';
314 | 
315 | const DebuggedComponent: React.FC = () => {
316 |   const gun = useGunContext();
317 |   const profileRef = gun.get('user').get('profile');
318 |   
319 |   // Debug all updates in development
320 |   useGunDebug(profileRef, 'UserProfile', process.env.NODE_ENV === 'development');
321 |   
322 |   const { fields } = useGunState(profileRef);
323 |   
324 |   return <div>{fields.name}</div>;
325 | };
326 | ```
327 | 
328 | ## Performance Tips
329 | 
330 | ### Memoization
331 | 
332 | ```typescript
333 | import { useMemo, useCallback } from 'react';
334 | 
335 | const OptimizedComponent: React.FC = () => {
336 |   const { fields, put } = useGunState(ref);
337 |   
338 |   // Memoize expensive computations
339 |   const processedData = useMemo(() => {
340 |     return Object.keys(fields).map(key => ({
341 |       key,
342 |       value: fields[key],
343 |       processed: true
344 |     }));
345 |   }, [fields]);
346 |   
347 |   // Memoize event handlers
348 |   const handleUpdate = useCallback(async (newData) => {
349 |     await put(newData);
350 |   }, [put]);
351 |   
352 |   return (
353 |     <div>
354 |       {processedData.map(item => (
355 |         <div key={item.key}>{item.value}</div>
356 |       ))}
357 |     </div>
358 |   );
359 | };
360 | ```
361 | 
362 | ## Best Practices
363 | 
364 | 1. **Always handle errors** - Check the `error` state and provide user feedback
365 | 2. **Show loading states** - Use `isLoading` for better UX
366 | 3. **Monitor connections** - Use `isConnected` for network status
367 | 4. **Use TypeScript** - Define interfaces for your data structures
368 | 5. **Validate inputs** - The hook validates automatically, but add your own validation
369 | 6. **Handle async operations** - Use try-catch with `put` and `remove`
370 | 7. **Optimize renders** - Use memoization for expensive operations
371 | 


--------------------------------------------------------------------------------
/docs/useGunKeyAuth.md:
--------------------------------------------------------------------------------
  1 | # useGunKeyAuth
  2 | 
  3 | A hook that handles user authentication using Gun key pairs with comprehensive error handling and status monitoring.
  4 | 
  5 | ## Overview
  6 | 
  7 | `useGunKeyAuth` provides secure authentication functionality for GunDB applications. It manages the authentication process, handles errors gracefully, and provides real-time status updates for a complete authentication experience.
  8 | 
  9 | ## API Reference
 10 | 
 11 | ### Signature
 12 | 
 13 | ```typescript
 14 | useGunKeyAuth(
 15 |   gun: GunRef,
 16 |   keys: KeyPair,
 17 |   triggerAuth?: boolean
 18 | ): [IGunUserReference, boolean, GunError | null]
 19 | ```
 20 | 
 21 | ### Parameters
 22 | 
 23 | - `gun` - Gun instance
 24 | - `keys` - Key pair for authentication
 25 | - `triggerAuth` - Whether to trigger authentication immediately (default: `true`)
 26 | 
 27 | ### Return Type
 28 | 
 29 | ```typescript
 30 | [
 31 |   namespacedGraph: IGunUserReference,  // Authenticated user reference
 32 |   isLoggedIn: boolean,                 // Authentication status
 33 |   authError: GunError | null           // Authentication error
 34 | ]
 35 | ```
 36 | 
 37 | ### Key Pair Type
 38 | 
 39 | ```typescript
 40 | interface KeyPair {
 41 |   pub: string; // Public key
 42 |   priv: string; // Private key
 43 |   epub: string; // Encrypted public key
 44 |   epriv: string; // Encrypted private key
 45 | }
 46 | ```
 47 | 
 48 | ## Basic Usage
 49 | 
 50 | ### Simple Authentication
 51 | 
 52 | ```typescript
 53 | import React from 'react';
 54 | import { useGun, useGunKeyAuth, useGunKeys } from '@altrx/gundb-react-hooks';
 55 | import Gun from 'gun';
 56 | import SEA from 'gun/sea';
 57 | 
 58 | export const AuthApp: React.FC = () => {
 59 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
 60 |   const appKeys = useGunKeys(SEA);
 61 |   const [user, isLoggedIn, authError] = useGunKeyAuth(gun, appKeys!);
 62 | 
 63 |   // Handle authentication errors
 64 |   if (authError) {
 65 |     return (
 66 |       <div className="auth-error">
 67 |         <h3>Authentication Failed</h3>
 68 |         <p><strong>Error:</strong> {authError.err}</p>
 69 |         {authError.context && (
 70 |           <p><strong>Context:</strong> {authError.context}</p>
 71 |         )}
 72 |         <button onClick={() => window.location.reload()}>
 73 |           Try Again
 74 |         </button>
 75 |       </div>
 76 |     );
 77 |   }
 78 | 
 79 |   // Handle key generation
 80 |   if (!appKeys) {
 81 |     return (
 82 |       <div className="key-generation">
 83 |         <h3>Generating Keys...</h3>
 84 |         <p>Creating your secure key pair</p>
 85 |       </div>
 86 |     );
 87 |   }
 88 | 
 89 |   // Handle authentication in progress
 90 |   if (!isLoggedIn) {
 91 |     return (
 92 |       <div className="authenticating">
 93 |         <h3>Authenticating...</h3>
 94 |         <p>Logging you in securely</p>
 95 |       </div>
 96 |     );
 97 |   }
 98 | 
 99 |   // Successful authentication
100 |   return (
101 |     <div className="authenticated">
102 |       <h2>Welcome! You're authenticated</h2>
103 |       <p><strong>Public Key:</strong> {appKeys.pub}</p>
104 |       <UserDashboard user={user} />
105 |     </div>
106 |   );
107 | };
108 | 
109 | const UserDashboard: React.FC<{ user: any }> = ({ user }) => {
110 |   return (
111 |     <div>
112 |       <h3>User Dashboard</h3>
113 |       <p>You can now access encrypted data and perform authenticated operations.</p>
114 |       <button onClick={() => user.leave()}>Logout</button>
115 |     </div>
116 |   );
117 | };
118 | ```
119 | 
120 | ## Advanced Usage
121 | 
122 | ### Conditional Authentication
123 | 
124 | ```typescript
125 | import React, { useState } from 'react';
126 | import { useGunKeyAuth, useGunKeys } from '@altrx/gundb-react-hooks';
127 | 
128 | export const ConditionalAuthApp: React.FC = () => {
129 |   const [shouldAuth, setShouldAuth] = useState(false);
130 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
131 |   const appKeys = useGunKeys(SEA);
132 | 
133 |   // Only authenticate when user explicitly wants to
134 |   const [user, isLoggedIn, authError] = useGunKeyAuth(gun, appKeys!, shouldAuth);
135 | 
136 |   if (authError) {
137 |     return (
138 |       <div>
139 |         <h3>Authentication Error</h3>
140 |         <p>{authError.err}</p>
141 |         <button onClick={() => setShouldAuth(false)}>Cancel</button>
142 |         <button onClick={() => setShouldAuth(true)}>Retry</button>
143 |       </div>
144 |     );
145 |   }
146 | 
147 |   if (!appKeys) return <div>Generating keys...</div>;
148 | 
149 |   if (!shouldAuth) {
150 |     return (
151 |       <div>
152 |         <h2>Welcome to the App</h2>
153 |         <p>Click below to authenticate and access your data</p>
154 |         <button onClick={() => setShouldAuth(true)}>
155 |           Login with Gun
156 |         </button>
157 |       </div>
158 |     );
159 |   }
160 | 
161 |   if (!isLoggedIn) {
162 |     return (
163 |       <div>
164 |         <p>Authenticating...</p>
165 |         <button onClick={() => setShouldAuth(false)}>Cancel</button>
166 |       </div>
167 |     );
168 |   }
169 | 
170 |   return (
171 |     <div>
172 |       <h2>Authenticated Successfully!</h2>
173 |       <button onClick={() => {
174 |         user.leave();
175 |         setShouldAuth(false);
176 |       }}>
177 |         Logout
178 |       </button>
179 |     </div>
180 |   );
181 | };
182 | ```
183 | 
184 | ### Authentication with User Registration
185 | 
186 | ```typescript
187 | import React, { useState } from 'react';
188 | import { useGun, useGunKeyAuth, useGunState } from '@altrx/gundb-react-hooks';
189 | import SEA from 'gun/sea';
190 | 
191 | interface UserProfile {
192 |   username: string;
193 |   email: string;
194 |   createdAt: string;
195 | }
196 | 
197 | export const AuthWithRegistration: React.FC = () => {
198 |   const [isNewUser, setIsNewUser] = useState(false);
199 |   const [storedKeys, setStoredKeys] = useState<KeyPair | null>(null);
200 | 
201 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
202 | 
203 |   // Generate new keys or use stored keys
204 |   const keys = useGunKeys(SEA, storedKeys);
205 |   const [user, isLoggedIn, authError] = useGunKeyAuth(gun, keys!);
206 | 
207 |   const handleCreateAccount = async () => {
208 |     if (!keys) return;
209 | 
210 |     try {
211 |       // Store keys locally for future use (in real app, use secure storage)
212 |       localStorage.setItem('gunKeys', JSON.stringify(keys));
213 |       setStoredKeys(keys);
214 |       setIsNewUser(true);
215 |     } catch (error) {
216 |       console.error('Failed to create account:', error);
217 |     }
218 |   };
219 | 
220 |   const handleLogin = () => {
221 |     const savedKeys = localStorage.getItem('gunKeys');
222 |     if (savedKeys) {
223 |       setStoredKeys(JSON.parse(savedKeys));
224 |     } else {
225 |       alert('No saved keys found. Please create an account first.');
226 |     }
227 |   };
228 | 
229 |   if (authError) {
230 |     return (
231 |       <div className="auth-error">
232 |         <h3>Authentication Error</h3>
233 |         <p>{authError.err}</p>
234 |         <button onClick={() => window.location.reload()}>Try Again</button>
235 |       </div>
236 |     );
237 |   }
238 | 
239 |   if (!keys) return <div>Generating keys...</div>;
240 | 
241 |   if (!storedKeys && !isLoggedIn) {
242 |     return (
243 |       <div className="auth-choice">
244 |         <h2>Welcome to Gun App</h2>
245 |         <button onClick={handleCreateAccount}>Create New Account</button>
246 |         <button onClick={handleLogin}>Login with Existing Keys</button>
247 |       </div>
248 |     );
249 |   }
250 | 
251 |   if (!isLoggedIn) {
252 |     return <div>Authenticating...</div>;
253 |   }
254 | 
255 |   return (
256 |     <AuthenticatedApp user={user} keys={keys} isNewUser={isNewUser} />
257 |   );
258 | };
259 | 
260 | const AuthenticatedApp: React.FC<{
261 |   user: any;
262 |   keys: KeyPair;
263 |   isNewUser: boolean;
264 | }> = ({ user, keys, isNewUser }) => {
265 |   const {
266 |     fields: profile,
267 |     put: updateProfile,
268 |     error: profileError
269 |   } = useGunState<UserProfile>(user.get('profile'));
270 | 
271 |   const [username, setUsername] = useState('');
272 | 
273 |   const handleSetupProfile = async () => {
274 |     if (!username.trim()) return;
275 | 
276 |     try {
277 |       await updateProfile({
278 |         username,
279 |         email: '', // Can be added later
280 |         createdAt: new Date().toISOString()
281 |       });
282 |     } catch (error) {
283 |       console.error('Failed to setup profile:', error);
284 |     }
285 |   };
286 | 
287 |   if (profileError) {
288 |     return <div>Profile Error: {profileError.err}</div>;
289 |   }
290 | 
291 |   if (isNewUser && !profile.username) {
292 |     return (
293 |       <div className="profile-setup">
294 |         <h2>Setup Your Profile</h2>
295 |         <input
296 |           type="text"
297 |           placeholder="Enter username"
298 |           value={username}
299 |           onChange={(e) => setUsername(e.target.value)}
300 |         />
301 |         <button onClick={handleSetupProfile}>Save Profile</button>
302 |       </div>
303 |     );
304 |   }
305 | 
306 |   return (
307 |     <div className="user-dashboard">
308 |       <h2>Welcome, {profile.username || 'User'}!</h2>
309 |       <div className="user-info">
310 |         <p><strong>Public Key:</strong> {keys.pub.slice(0, 20)}...</p>
311 |         <p><strong>Member since:</strong> {
312 |           profile.createdAt ? new Date(profile.createdAt).toLocaleDateString() : 'Unknown'
313 |         }</p>
314 |       </div>
315 |       <button onClick={() => {
316 |         user.leave();
317 |         localStorage.removeItem('gunKeys');
318 |         window.location.reload();
319 |       }}>
320 |         Logout
321 |       </button>
322 |     </div>
323 |   );
324 | };
325 | ```
326 | 
327 | ## Error Handling
328 | 
329 | ### Comprehensive Error Handling
330 | 
331 | ```typescript
332 | const AuthWithErrorHandling: React.FC = () => {
333 |   const [retryCount, setRetryCount] = useState(0);
334 |   const [manualRetry, setManualRetry] = useState(false);
335 | 
336 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
337 |   const keys = useGunKeys(SEA);
338 |   const [user, isLoggedIn, authError] = useGunKeyAuth(gun, keys!, !manualRetry);
339 | 
340 |   // Handle different types of authentication errors
341 |   const handleAuthError = (error: GunError) => {
342 |     switch (error.context) {
343 |       case 'useGunKeyAuth.auth':
344 |         return (
345 |           <div className="auth-failed">
346 |             <h3>Authentication Failed</h3>
347 |             <p>Your credentials could not be verified.</p>
348 |             <button onClick={() => {
349 |               setRetryCount(prev => prev + 1);
350 |               setManualRetry(false);
351 |             }}>
352 |               Retry Authentication ({retryCount} attempts)
353 |             </button>
354 |           </div>
355 |         );
356 | 
357 |       case 'useGunKeyAuth':
358 |         return (
359 |           <div className="auth-error">
360 |             <h3>Authentication Error</h3>
361 |             <p>{error.err}</p>
362 |             <button onClick={() => window.location.reload()}>
363 |               Restart App
364 |             </button>
365 |           </div>
366 |         );
367 | 
368 |       default:
369 |         return (
370 |           <div className="unknown-error">
371 |             <h3>Unknown Authentication Error</h3>
372 |             <p>{error.err}</p>
373 |             <details>
374 |               <summary>Error Details</summary>
375 |               <pre>{JSON.stringify(error, null, 2)}</pre>
376 |             </details>
377 |             <button onClick={() => setManualRetry(true)}>
378 |               Disable Auto-Auth
379 |             </button>
380 |           </div>
381 |         );
382 |     }
383 |   };
384 | 
385 |   if (authError) {
386 |     return handleAuthError(authError);
387 |   }
388 | 
389 |   // ... rest of component
390 | };
391 | ```
392 | 
393 | ## Migration from v0.9.x
394 | 
395 | ### Before (v0.9.x)
396 | 
397 | ```typescript
398 | const [user, isLoggedIn] = useGunKeyAuth(gun, keys);
399 | 
400 | // No error handling - authentication failures were silent or thrown exceptions
401 | if (isLoggedIn) {
402 |   // Proceed with authenticated user
403 | }
404 | ```
405 | 
406 | ### After (v1.0.0)
407 | 
408 | ```typescript
409 | const [user, isLoggedIn, authError] = useGunKeyAuth(gun, keys);
410 | 
411 | // Explicit error handling
412 | if (authError) {
413 |   console.error('Authentication failed:', authError.err);
414 |   // Handle error appropriately
415 |   return <AuthErrorComponent error={authError} />;
416 | }
417 | 
418 | if (isLoggedIn) {
419 |   // Proceed with authenticated user
420 | }
421 | ```
422 | 
423 | ## Security Best Practices
424 | 
425 | ### Key Storage and Management
426 | 
427 | ```typescript
428 | // Don't store keys in plain text
429 | localStorage.setItem('keys', JSON.stringify(keys));
430 | 
431 | // Use secure storage methods
432 | const storeKeysSecurely = async (keys: KeyPair) => {
433 |   // In a real app, use:
434 |   // - Encrypted local storage
435 |   // - Hardware security modules
436 |   // - Secure key management services
437 | 
438 |   const encrypted = await SEA.encrypt(keys, userPassword);
439 |   localStorage.setItem('encryptedKeys', encrypted);
440 | };
441 | 
442 | // Validate keys before use
443 | const validateKeys = (keys: KeyPair): boolean => {
444 |   return !!(keys.pub && keys.priv && keys.epub && keys.epriv);
445 | };
446 | ```
447 | 
448 | ### Authentication State Management
449 | 
450 | ```typescript
451 | const SecureAuthFlow: React.FC = () => {
452 |   const [authAttempts, setAuthAttempts] = useState(0);
453 |   const [isLocked, setIsLocked] = useState(false);
454 | 
455 |   const [user, isLoggedIn, authError] = useGunKeyAuth(gun, keys!);
456 | 
457 |   useEffect(() => {
458 |     if (authError) {
459 |       setAuthAttempts(prev => prev + 1);
460 | 
461 |       // Lock after 3 failed attempts
462 |       if (authAttempts >= 3) {
463 |         setIsLocked(true);
464 |         setTimeout(() => setIsLocked(false), 60000); // 1 minute lockout
465 |       }
466 |     }
467 |   }, [authError, authAttempts]);
468 | 
469 |   if (isLocked) {
470 |     return <div>Too many failed attempts. Please wait 1 minute.</div>;
471 |   }
472 | 
473 |   // ... rest of component
474 | };
475 | ```
476 | 
477 | ## Best Practices
478 | 
479 | 1. **Always handle authentication errors** - Check the `authError` state
480 | 2. **Implement retry mechanisms** - Allow users to retry failed authentications
481 | 3. **Store keys securely** - Never store keys in plain text
482 | 4. **Validate key pairs** - Ensure keys are complete before authentication
483 | 5. **Monitor authentication attempts** - Implement lockout mechanisms for security
484 | 6. **Provide clear feedback** - Show users what's happening during authentication
485 | 7. **Handle network issues** - Authentication can fail due to connectivity problems
486 | 8. **Use conditional authentication** - Don't always authenticate immediately
487 | 


--------------------------------------------------------------------------------
/docs/useGunNamespace.md:
--------------------------------------------------------------------------------
  1 | # useGunNamespace
  2 | 
  3 | A hook that creates or retrieves a namespaced Gun graph reference with enhanced error handling and type safety.
  4 | 
  5 | ## Overview
  6 | 
  7 | `useGunNamespace` provides a way to create isolated data spaces within your GunDB application. It allows you to organize data logically, implement multi-tenancy, and manage separate contexts within your application while maintaining proper error handling and type safety.
  8 | 
  9 | ## API Reference
 10 | 
 11 | ### Signature
 12 | 
 13 | ```typescript
 14 | useGunNamespace(
 15 |   gun: IGunInstance,
 16 |   soul?: string
 17 | ): IGunReference
 18 | ```
 19 | 
 20 | ### Parameters
 21 | 
 22 | - `gun` - Gun instance to create namespace from
 23 | - `soul` - Optional soul/ID for specific namespace (generates new if not provided)
 24 | 
 25 | ### Return Type
 26 | 
 27 | ```typescript
 28 | IGunReference; // Namespaced Gun graph reference
 29 | ```
 30 | 
 31 | ## Basic Usage
 32 | 
 33 | ### Auto-Generated Namespace
 34 | 
 35 | ```typescript
 36 | import React from 'react';
 37 | import { useGun, useGunNamespace, useGunState } from '@altrx/gundb-react-hooks';
 38 | import Gun from 'gun';
 39 | 
 40 | export const NamespaceExample: React.FC = () => {
 41 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
 42 | 
 43 |   // Create a new namespace with auto-generated soul
 44 |   const namespacedGraph = useGunNamespace(gun);
 45 | 
 46 |   // Use the namespace for state management
 47 |   const {
 48 |     fields: userData,
 49 |     put: updateUserData,
 50 |     error: userError
 51 |   } = useGunState(namespacedGraph);
 52 | 
 53 |   const handleSaveData = async () => {
 54 |     try {
 55 |       await updateUserData({
 56 |         name: 'John Doe',
 57 |         preferences: { theme: 'dark', language: 'en' },
 58 |         lastUpdated: new Date().toISOString()
 59 |       });
 60 |       console.log('Data saved to namespace');
 61 |     } catch (error) {
 62 |       console.error('Failed to save data:', error);
 63 |     }
 64 |   };
 65 | 
 66 |   if (userError) {
 67 |     return (
 68 |       <div className="namespace-error">
 69 |         <h3>Namespace Error</h3>
 70 |         <p>{userError.err}</p>
 71 |       </div>
 72 |     );
 73 |   }
 74 | 
 75 |   return (
 76 |     <div className="namespace-demo">
 77 |       <h3>Auto-Generated Namespace</h3>
 78 | 
 79 |       <div className="namespace-info">
 80 |         <p><strong>Namespace Soul:</strong> {namespacedGraph._.opt?.soul || 'Generating...'}</p>
 81 |         <p><strong>Data:</strong> {JSON.stringify(userData, null, 2)}</p>
 82 |       </div>
 83 | 
 84 |       <button onClick={handleSaveData}>
 85 |         Save Data to Namespace
 86 |       </button>
 87 |     </div>
 88 |   );
 89 | };
 90 | ```
 91 | 
 92 | ### Specific Namespace (Known Soul)
 93 | 
 94 | ```typescript
 95 | import React, { useState } from 'react';
 96 | import { useGun, useGunNamespace, useGunState } from '@altrx/gundb-react-hooks';
 97 | 
 98 | export const SpecificNamespaceExample: React.FC = () => {
 99 |   const [targetSoul, setTargetSoul] = useState<string>('user_settings_12345');
100 |   const [currentSoul, setCurrentSoul] = useState<string>(targetSoul);
101 | 
102 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
103 | 
104 |   // Connect to specific namespace
105 |   const namespacedGraph = useGunNamespace(gun, currentSoul);
106 | 
107 |   const {
108 |     fields: settings,
109 |     put: updateSettings,
110 |     error: settingsError
111 |   } = useGunState(namespacedGraph);
112 | 
113 |   const switchNamespace = () => {
114 |     setCurrentSoul(targetSoul);
115 |   };
116 | 
117 |   const saveSettings = async () => {
118 |     try {
119 |       await updateSettings({
120 |         theme: 'dark',
121 |         notifications: true,
122 |         autoSave: false,
123 |         language: 'en-US',
124 |         updatedAt: new Date().toISOString()
125 |       });
126 |     } catch (error) {
127 |       console.error('Failed to save settings:', error);
128 |     }
129 |   };
130 | 
131 |   return (
132 |     <div className="specific-namespace">
133 |       <h3>Specific Namespace</h3>
134 | 
135 |       <div className="namespace-controls">
136 |         <input
137 |           type="text"
138 |           placeholder="Enter namespace soul/ID"
139 |           value={targetSoul}
140 |           onChange={(e) => setTargetSoul(e.target.value)}
141 |         />
142 |         <button onClick={switchNamespace}>
143 |           Switch to Namespace
144 |         </button>
145 |       </div>
146 | 
147 |       <div className="namespace-info">
148 |         <p><strong>Current Namespace:</strong> {currentSoul}</p>
149 |         <p><strong>Connected:</strong> {namespacedGraph ? 'Yes' : 'No'}</p>
150 |       </div>
151 | 
152 |       {settingsError ? (
153 |         <div className="error">
154 |           <p>Error: {settingsError.err}</p>
155 |         </div>
156 |       ) : (
157 |         <div className="settings-display">
158 |           <h4>Settings Data:</h4>
159 |           <pre>{JSON.stringify(settings, null, 2)}</pre>
160 |           <button onClick={saveSettings}>
161 |             Save Settings
162 |           </button>
163 |         </div>
164 |       )}
165 |     </div>
166 |   );
167 | };
168 | ```
169 | 
170 | ## Advanced Usage
171 | 
172 | ### Multi-Tenant Application
173 | 
174 | ```typescript
175 | import React, { useState, useEffect } from 'react';
176 | import { useGun, useGunNamespace, useGunState } from '@altrx/gundb-react-hooks';
177 | 
178 | interface Tenant {
179 |   id: string;
180 |   name: string;
181 |   namespace: string;
182 | }
183 | 
184 | export const MultiTenantApp: React.FC = () => {
185 |   const [selectedTenant, setSelectedTenant] = useState<Tenant | null>(null);
186 |   const [tenants] = useState<Tenant[]>([
187 |     { id: '1', name: 'Company A', namespace: 'tenant_company_a' },
188 |     { id: '2', name: 'Company B', namespace: 'tenant_company_b' },
189 |     { id: '3', name: 'Company C', namespace: 'tenant_company_c' }
190 |   ]);
191 | 
192 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
193 | 
194 |   // Create namespace for selected tenant
195 |   const tenantGraph = useGunNamespace(gun, selectedTenant?.namespace);
196 | 
197 |   const {
198 |     fields: tenantData,
199 |     put: updateTenantData,
200 |     error: tenantError
201 |   } = useGunState(tenantGraph);
202 | 
203 |   const selectTenant = (tenant: Tenant) => {
204 |     setSelectedTenant(tenant);
205 |   };
206 | 
207 |   const saveTenantData = async () => {
208 |     if (!selectedTenant) return;
209 | 
210 |     try {
211 |       await updateTenantData({
212 |         tenantId: selectedTenant.id,
213 |         name: selectedTenant.name,
214 |         settings: {
215 |           maxUsers: 100,
216 |           features: ['analytics', 'reporting', 'api'],
217 |           subscription: 'premium'
218 |         },
219 |         lastAccessed: new Date().toISOString()
220 |       });
221 |     } catch (error) {
222 |       console.error('Failed to save tenant data:', error);
223 |     }
224 |   };
225 | 
226 |   return (
227 |     <div className="multi-tenant-app">
228 |       <h3>Multi-Tenant Application</h3>
229 | 
230 |       <div className="tenant-selector">
231 |         <h4>Select Tenant:</h4>
232 |         {tenants.map(tenant => (
233 |           <button
234 |             key={tenant.id}
235 |             onClick={() => selectTenant(tenant)}
236 |             className={selectedTenant?.id === tenant.id ? 'active' : ''}
237 |           >
238 |             {tenant.name}
239 |           </button>
240 |         ))}
241 |       </div>
242 | 
243 |       {selectedTenant ? (
244 |         <div className="tenant-workspace">
245 |           <h4>Tenant: {selectedTenant.name}</h4>
246 |           <p><strong>Namespace:</strong> {selectedTenant.namespace}</p>
247 | 
248 |           {tenantError ? (
249 |             <div className="error">
250 |               <p>Error loading tenant data: {tenantError.err}</p>
251 |             </div>
252 |           ) : (
253 |             <div className="tenant-data">
254 |               <h5>Tenant Data:</h5>
255 |               <pre>{JSON.stringify(tenantData, null, 2)}</pre>
256 |               <button onClick={saveTenantData}>
257 |                 Save Tenant Data
258 |               </button>
259 |             </div>
260 |           )}
261 |         </div>
262 |       ) : (
263 |         <div className="no-tenant">
264 |           <p>Please select a tenant to view their data</p>
265 |         </div>
266 |       )}
267 |     </div>
268 |   );
269 | };
270 | ```
271 | 
272 | ### Dynamic Namespace Creation
273 | 
274 | ```typescript
275 | import React, { useState } from 'react';
276 | import { useGun, useGunNamespace, useGunCollectionState } from '@altrx/gundb-react-hooks';
277 | 
278 | interface Project {
279 |   id: string;
280 |   name: string;
281 |   description: string;
282 |   createdAt: string;
283 | }
284 | 
285 | export const ProjectManager: React.FC = () => {
286 |   const [projects, setProjects] = useState<string[]>([]);
287 |   const [newProjectName, setNewProjectName] = useState<string>('');
288 |   const [selectedProject, setSelectedProject] = useState<string | null>(null);
289 | 
290 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
291 | 
292 |   // Create namespace for selected project
293 |   const projectGraph = useGunNamespace(gun, selectedProject || undefined);
294 | 
295 |   const {
296 |     collection: projectData,
297 |     addToCollection: addProjectData,
298 |     error: projectError
299 |   } = useGunCollectionState<Project>(projectGraph);
300 | 
301 |   const createProject = () => {
302 |     if (!newProjectName.trim()) return;
303 | 
304 |     const projectId = `project_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
305 |     setProjects(prev => [...prev, projectId]);
306 |     setSelectedProject(projectId);
307 |     setNewProjectName('');
308 | 
309 |     // Initialize project data
310 |     setTimeout(() => {
311 |       addProjectData({
312 |         id: projectId,
313 |         name: newProjectName,
314 |         description: `Project ${newProjectName}`,
315 |         createdAt: new Date().toISOString()
316 |       });
317 |     }, 100);
318 |   };
319 | 
320 |   const selectProject = (projectId: string) => {
321 |     setSelectedProject(projectId);
322 |   };
323 | 
324 |   const addProjectItem = async () => {
325 |     if (!selectedProject) return;
326 | 
327 |     try {
328 |       await addProjectData({
329 |         id: `item_${Date.now()}`,
330 |         name: `Task ${Object.keys(projectData).length + 1}`,
331 |         description: 'New project task',
332 |         createdAt: new Date().toISOString()
333 |       });
334 |     } catch (error) {
335 |       console.error('Failed to add project item:', error);
336 |     }
337 |   };
338 | 
339 |   return (
340 |     <div className="project-manager">
341 |       <h3>Dynamic Project Namespaces</h3>
342 | 
343 |       <div className="project-creation">
344 |         <h4>Create New Project:</h4>
345 |         <input
346 |           type="text"
347 |           placeholder="Project name"
348 |           value={newProjectName}
349 |           onChange={(e) => setNewProjectName(e.target.value)}
350 |           onKeyPress={(e) => e.key === 'Enter' && createProject()}
351 |         />
352 |         <button onClick={createProject} disabled={!newProjectName.trim()}>
353 |           Create Project
354 |         </button>
355 |       </div>
356 | 
357 |       <div className="project-list">
358 |         <h4>Existing Projects:</h4>
359 |         {projects.map(projectId => (
360 |           <button
361 |             key={projectId}
362 |             onClick={() => selectProject(projectId)}
363 |             className={selectedProject === projectId ? 'active' : ''}
364 |           >
365 |             {projectId.replace('project_', '').split('_')[1]}
366 |           </button>
367 |         ))}
368 |       </div>
369 | 
370 |       {selectedProject && (
371 |         <div className="project-workspace">
372 |           <h4>Project: {selectedProject}</h4>
373 | 
374 |           {projectError ? (
375 |             <div className="error">
376 |               <p>Error: {projectError.err}</p>
377 |             </div>
378 |           ) : (
379 |             <div className="project-content">
380 |               <div className="project-actions">
381 |                 <button onClick={addProjectItem}>
382 |                   Add Task
383 |                 </button>
384 |               </div>
385 | 
386 |               <div className="project-items">
387 |                 <h5>Project Items ({Object.keys(projectData).length}):</h5>
388 |                 {Object.entries(projectData).map(([key, item]) => (
389 |                   <div key={key} className="project-item">
390 |                     <h6>{item.name}</h6>
391 |                     <p>{item.description}</p>
392 |                     <small>Created: {new Date(item.createdAt).toLocaleDateString()}</small>
393 |                   </div>
394 |                 ))}
395 |               </div>
396 |             </div>
397 |           )}
398 |         </div>
399 |       )}
400 |     </div>
401 |   );
402 | };
403 | ```
404 | 
405 | ## Error Handling
406 | 
407 | ### Namespace Error Management
408 | 
409 | ```typescript
410 | const NamespaceWithErrorHandling: React.FC = () => {
411 |   const [soul, setSoul] = useState<string>('valid_namespace');
412 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
413 | 
414 |   const namespacedGraph = useGunNamespace(gun, soul);
415 |   const { fields, error } = useGunState(namespacedGraph);
416 | 
417 |   // Monitor for namespace-related errors
418 |   useEffect(() => {
419 |     if (error?.context?.includes('namespace')) {
420 |       console.error('Namespace error:', error);
421 |       // Handle namespace-specific errors
422 |     }
423 |   }, [error]);
424 | 
425 |   return (
426 |     <div>
427 |       {error ? (
428 |         <div className="namespace-error">
429 |           <p>Namespace Error: {error.err}</p>
430 |           <button onClick={() => setSoul(`fallback_${Date.now()}`)}>
431 |             Create Fallback Namespace
432 |           </button>
433 |         </div>
434 |       ) : (
435 |         <div>
436 |           <p>Namespace: {soul}</p>
437 |           <pre>{JSON.stringify(fields, null, 2)}</pre>
438 |         </div>
439 |       )}
440 |     </div>
441 |   );
442 | };
443 | ```
444 | 
445 | ## Migration from v0.9.x
446 | 
447 | ## Best Practices
448 | 
449 | ### Namespace Organization
450 | 
451 | ```typescript
452 | // Good: Use descriptive, hierarchical naming
453 | const userNamespace = useGunNamespace(gun, `user_${userId}`);
454 | const settingsNamespace = useGunNamespace(gun, `user_${userId}_settings`);
455 | const chatNamespace = useGunNamespace(gun, `chat_${chatId}`);
456 | 
457 | // Avoid: Generic or unclear names
458 | const namespace1 = useGunNamespace(gun, 'data');
459 | const namespace2 = useGunNamespace(gun, 'stuff');
460 | ```
461 | 
462 | 1. **Use Descriptive Names** - Create meaningful namespace identifiers
463 | 2. **Implement Hierarchy** - Use structured naming conventions
464 | 3. **Isolate Data Properly** - Separate different types of data
465 | 4. **Handle Errors Gracefully** - Always check for namespace errors
466 | 5. **Cache References** - Reuse namespace references when possible
467 | 6. **Validate Souls** - Ensure namespace identifiers are safe
468 | 7. **Monitor Performance** - Track namespace usage and cleanup
469 | 8. **Document Structure** - Maintain clear namespace organization
470 | 


--------------------------------------------------------------------------------
/docs/useGunCollectionStatePaginated.md:
--------------------------------------------------------------------------------
  1 | # useGunCollectionStatePaginated
  2 | 
  3 | A high-performance, memory-efficient hook for managing paginated GunDB collections with smart caching, real-time updates, and comprehensive filtering/sorting capabilities.
  4 | 
  5 | ## Overview
  6 | 
  7 | `useGunCollectionStatePaginated` extends the functionality of `useGunCollectionState` by adding optimized pagination features designed for large datasets. It provides intelligent caching, preloading, and memory management while maintaining real-time synchronization with the GunDB network.
  8 | 
  9 | ## Features
 10 | 
 11 | - **Memory Efficient** - Only loads current page + preloaded pages
 12 | - **Smart Caching** - Page-level caching with configurable TTL (default 5 minutes)
 13 | - **Real-time Updates** - Live synchronization with debounced updates
 14 | - **Preloading** - Configurable page preloading for smooth navigation
 15 | - **Filtering & Sorting** - Client-side data processing with type safety
 16 | - **Performance Monitoring** - Built-in cache statistics and performance metrics
 17 | - **Seamless Migration** - Drop-in replacement for `useGunCollectionState`
 18 | 
 19 | ## Basic Usage
 20 | 
 21 | ```typescript
 22 | import { useGunCollectionStatePaginated } from '@altrx/gundb-react-hooks';
 23 | 
 24 | interface TodoItem {
 25 |   id: string;
 26 |   text: string;
 27 |   completed: boolean;
 28 |   createdAt: string;
 29 | }
 30 | 
 31 | function PaginatedTodoList() {
 32 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
 33 | 
 34 |   const {
 35 |     currentPageItems,
 36 |     currentPage,
 37 |     totalPages,
 38 |     pageSize,
 39 |     nextPage,
 40 |     prevPage,
 41 |     goToPage,
 42 |     setPageSize,
 43 |     hasNextPage,
 44 |     hasPrevPage,
 45 |     isLoadingPage,
 46 |     totalItems,
 47 |     addToSet,
 48 |     updateInSet,
 49 |     removeFromSet,
 50 |     error
 51 |   } = useGunCollectionStatePaginated<TodoItem>(
 52 |     gun.get('todos'),
 53 |     {
 54 |       pageSize: 10,
 55 |       sortBy: 'createdAt',
 56 |       sortOrder: 'desc'
 57 |     }
 58 |   );
 59 | 
 60 |   if (error) {
 61 |     return <div>Error: {error.err}</div>;
 62 |   }
 63 | 
 64 |   return (
 65 |     <div>
 66 |       <h2>Todos (Page {currentPage + 1} of {totalPages})</h2>
 67 | 
 68 |       {isLoadingPage ? (
 69 |         <div>Loading page...</div>
 70 |       ) : (
 71 |         <div>
 72 |           {currentPageItems.map(todo => (
 73 |             <div key={todo.nodeID}>
 74 |               <span>{todo.text}</span>
 75 |               <button onClick={() => updateInSet(todo.nodeID, {
 76 |                 completed: !todo.completed
 77 |               })}>
 78 |                 Toggle
 79 |               </button>
 80 |             </div>
 81 |           ))}
 82 |         </div>
 83 |       )}
 84 | 
 85 |       <div>
 86 |         <button onClick={prevPage} disabled={!hasPrevPage}>
 87 |           Previous
 88 |         </button>
 89 |         <span>Page {currentPage + 1} of {totalPages}</span>
 90 |         <button onClick={nextPage} disabled={!hasNextPage}>
 91 |           Next
 92 |         </button>
 93 |       </div>
 94 |     </div>
 95 |   );
 96 | }
 97 | ```
 98 | 
 99 | ## API Reference
100 | 
101 | ### Parameters
102 | 
103 | ```typescript
104 | useGunCollectionStatePaginated<T>(
105 |   ref: IGunChainReference,
106 |   options?: PaginationOptions<T>
107 | )
108 | ```
109 | 
110 | #### `ref: IGunChainReference`
111 | 
112 | The GunDB reference to the collection/set to paginate.
113 | 
114 | #### `options: PaginationOptions<T>` (optional)
115 | 
116 | ```typescript
117 | interface PaginationOptions<T> {
118 |   pageSize?: number; // Items per page (default: 10)
119 |   sortBy?: keyof T; // Field to sort by
120 |   sortOrder?: 'asc' | 'desc'; // Sort direction (default: 'asc')
121 |   filter?: (item: T) => boolean; // Filter function
122 |   preloadPages?: number; // Pages to preload ahead (default: 1)
123 |   cacheTimeout?: number; // Cache TTL in ms (default: 300000 = 5min)
124 |   debounceMs?: number; // Update debounce time (default: 100ms)
125 |   appKeys?: KeyPair; // Encryption keys for private data
126 | }
127 | ```
128 | 
129 | ### Return Value
130 | 
131 | ```typescript
132 | interface UsePaginatedCollectionReturn<T> {
133 |   // Current page data
134 |   currentPageItems: NodeT<T>[]; // Items for current page
135 |   currentPage: number; // Current page index (0-based)
136 |   totalPages: number; // Total number of pages
137 |   currentPageCount: number; // Items on current page
138 | 
139 |   // Pagination controls
140 |   pageSize: number; // Current page size
141 |   setPageSize: (size: number) => void; // Change page size
142 |   nextPage: () => void; // Go to next page
143 |   prevPage: () => void; // Go to previous page
144 |   goToPage: (page: number) => void; // Go to specific page
145 | 
146 |   // Navigation state
147 |   hasNextPage: boolean; // Can navigate forward
148 |   hasPrevPage: boolean; // Can navigate backward
149 |   isLoadingPage: boolean; // Page loading state
150 | 
151 |   // Collection info
152 |   totalItems: number; // Total items in collection
153 |   collection: Map<string, NodeT<T>>; // Complete collection map
154 |   items: NodeT<T>[]; // All items (use with caution)
155 | 
156 |   // Collection operations (inherited from useGunCollectionState)
157 |   addToSet: (data: T, nodeID?: string) => Promise<void>;
158 |   updateInSet: (nodeID: string, data: Partial<T>) => Promise<void>;
159 |   removeFromSet: (nodeID: string) => Promise<void>;
160 | 
161 |   // Error handling
162 |   error: GunError | null; // Any errors that occurred
163 | 
164 |   // Performance monitoring
165 |   preloadedPages: Set<number>; // Currently cached pages
166 |   cacheStats: {
167 |     // Cache performance metrics
168 |     hits: number;
169 |     misses: number;
170 |     efficiency: number;
171 |   };
172 | }
173 | ```
174 | 
175 | ## Advanced Usage
176 | 
177 | ### Custom Filtering and Sorting
178 | 
179 | ```typescript
180 | function AdvancedTodoList() {
181 |   const [priority, setPriority] = useState<'all' | 'high' | 'medium' | 'low'>('all');
182 |   const [sortField, setSortField] = useState<keyof TodoItem>('createdAt');
183 | 
184 |   const {
185 |     currentPageItems,
186 |     currentPage,
187 |     totalPages,
188 |     nextPage,
189 |     prevPage,
190 |     setPageSize,
191 |     pageSize
192 |   } = useGunCollectionStatePaginated<TodoItem>(
193 |     gun.get('todos'),
194 |     {
195 |       pageSize: 15,
196 |       sortBy: sortField,
197 |       sortOrder: 'desc',
198 |       filter: (todo) => {
199 |         if (priority === 'all') return true;
200 |         return todo.priority === priority;
201 |       },
202 |       preloadPages: 2 // Preload 2 pages ahead
203 |     }
204 |   );
205 | 
206 |   return (
207 |     <div>
208 |       {/* Filter Controls */}
209 |       <div>
210 |         <select value={priority} onChange={(e) => setPriority(e.target.value)}>
211 |           <option value="all">All Priorities</option>
212 |           <option value="high">High Priority</option>
213 |           <option value="medium">Medium Priority</option>
214 |           <option value="low">Low Priority</option>
215 |         </select>
216 | 
217 |         <select value={sortField} onChange={(e) => setSortField(e.target.value)}>
218 |           <option value="createdAt">Created Date</option>
219 |           <option value="text">Text</option>
220 |           <option value="priority">Priority</option>
221 |         </select>
222 | 
223 |         <select value={pageSize} onChange={(e) => setPageSize(Number(e.target.value))}>
224 |           <option value={10}>10 per page</option>
225 |           <option value={25}>25 per page</option>
226 |           <option value={50}>50 per page</option>
227 |         </select>
228 |       </div>
229 | 
230 |       {/* Items */}
231 |       <div>
232 |         {currentPageItems.map(todo => (
233 |           <TodoItem key={todo.nodeID} todo={todo} />
234 |         ))}
235 |       </div>
236 | 
237 |       {/* Pagination */}
238 |       <Pagination
239 |         currentPage={currentPage}
240 |         totalPages={totalPages}
241 |         onNext={nextPage}
242 |         onPrev={prevPage}
243 |       />
244 |     </div>
245 |   );
246 | }
247 | ```
248 | 
249 | ### Performance Monitoring
250 | 
251 | ```typescript
252 | function PerformanceAwareList() {
253 |   const {
254 |     currentPageItems,
255 |     preloadedPages,
256 |     cacheStats,
257 |     totalItems,
258 |     totalPages,
259 |     isLoadingPage
260 |   } = useGunCollectionStatePaginated<TodoItem>(
261 |     gun.get('todos'),
262 |     {
263 |       pageSize: 20,
264 |       preloadPages: 3
265 |     }
266 |   );
267 | 
268 |   return (
269 |     <div>
270 |       {/* Performance Stats */}
271 |       <div className="performance-stats">
272 |         <h3>Performance Metrics</h3>
273 |         <p>Total Items: {totalItems}</p>
274 |         <p>Total Pages: {totalPages}</p>
275 |         <p>Cached Pages: {preloadedPages.size}</p>
276 |         <p>Cache Efficiency: {(cacheStats.efficiency * 100).toFixed(1)}%</p>
277 |         <p>Cache Hits: {cacheStats.hits}</p>
278 |         <p>Cache Misses: {cacheStats.misses}</p>
279 |         {isLoadingPage && <p>Loading page...</p>}
280 |       </div>
281 | 
282 |       {/* Items */}
283 |       <div>
284 |         {currentPageItems.map(item => (
285 |           <div key={item.nodeID}>{item.text}</div>
286 |         ))}
287 |       </div>
288 |     </div>
289 |   );
290 | }
291 | ```
292 | 
293 | ### Real-time Updates with Authentication
294 | 
295 | ```typescript
296 | function AuthenticatedPaginatedList() {
297 |   const { user, appKeys } = useAuth();
298 | 
299 |   const {
300 |     currentPageItems,
301 |     addToSet,
302 |     updateInSet,
303 |     removeFromSet,
304 |     error
305 |   } = useGunCollectionStatePaginated<TodoItem>(
306 |     user?.get('todos'),
307 |     {
308 |       pageSize: 15,
309 |       appKeys, // Enable encryption for private data
310 |       sortBy: 'createdAt',
311 |       sortOrder: 'desc',
312 |       debounceMs: 150 // Slightly longer debounce for better performance
313 |     }
314 |   );
315 | 
316 |   const handleAddTodo = async () => {
317 |     if (!user) return;
318 | 
319 |     try {
320 |       await addToSet({
321 |         id: `todo_${Date.now()}`,
322 |         text: 'New encrypted todo',
323 |         completed: false,
324 |         createdAt: new Date().toISOString(),
325 |         priority: 'medium'
326 |       });
327 |     } catch (error) {
328 |       console.error('Failed to add todo:', error);
329 |     }
330 |   };
331 | 
332 |   if (!user) {
333 |     return <div>Please log in to view your todos.</div>;
334 |   }
335 | 
336 |   if (error) {
337 |     return <div>Error loading todos: {error.err}</div>;
338 |   }
339 | 
340 |   return (
341 |     <div>
342 |       <button onClick={handleAddTodo}>Add Todo</button>
343 | 
344 |       {currentPageItems.map(todo => (
345 |         <div key={todo.nodeID}>
346 |           <span>{todo.text}</span>
347 |           <button onClick={() => removeFromSet(todo.nodeID)}>
348 |             Delete
349 |           </button>
350 |         </div>
351 |       ))}
352 |     </div>
353 |   );
354 | }
355 | ```
356 | 
357 | ## Migration from useGunCollectionState
358 | 
359 | The paginated hook is designed as a drop-in replacement with minimal code changes:
360 | 
361 | ```typescript
362 | // Before: useGunCollectionState
363 | const {
364 |   collection,
365 |   items,
366 |   addToSet,
367 |   updateInSet,
368 |   removeFromSet,
369 |   error,
370 |   isLoading,
371 |   count,
372 | } = useGunCollectionState<TodoItem>(ref);
373 | 
374 | // After: useGunCollectionStatePaginated
375 | const {
376 |   collection, // Same interface
377 |   items, // Same interface (but use currentPageItems instead)
378 |   currentPageItems, // New: items for current page
379 |   addToSet, // Same interface
380 |   updateInSet, // Same interface
381 |   removeFromSet, // Same interface
382 |   error, // Same interface
383 |   isLoading, // Renamed to isLoadingPage
384 |   count, // Renamed to totalItems
385 |   // ... pagination-specific properties
386 | } = useGunCollectionStatePaginated<TodoItem>(ref, {
387 |   pageSize: 10,
388 | });
389 | ```
390 | 
391 | ### Key Changes
392 | 
393 | 1. **Use `currentPageItems`** instead of `items` for rendering
394 | 2. **`isLoading`** becomes **`isLoadingPage`**
395 | 3. **`count`** becomes **`totalItems`**
396 | 4. **Add pagination options** to the second parameter
397 | 
398 | ## Performance Guidelines
399 | 
400 | ### Optimal Configuration
401 | 
402 | ```typescript
403 | // For small datasets (< 1000 items)
404 | const pagination = useGunCollectionStatePaginated(ref, {
405 |   pageSize: 25,
406 |   preloadPages: 1,
407 | });
408 | 
409 | // For medium datasets (1000-10000 items)
410 | const pagination = useGunCollectionStatePaginated(ref, {
411 |   pageSize: 50,
412 |   preloadPages: 2,
413 |   cacheTimeout: 300000, // 5 minutes
414 | });
415 | 
416 | // For large datasets (> 10000 items)
417 | const pagination = useGunCollectionStatePaginated(ref, {
418 |   pageSize: 100,
419 |   preloadPages: 1,
420 |   cacheTimeout: 600000, // 10 minutes
421 |   debounceMs: 200,
422 | });
423 | ```
424 | 
425 | ### Memory Management
426 | 
427 | - **Page Size**: 10-100 items per page depending on item complexity
428 | - **Preloading**: 1-3 pages ahead (more for better UX, fewer for memory)
429 | - **Cache Timeout**: 5-10 minutes for real-time apps, longer for static data
430 | - **Debouncing**: 100-200ms for optimal real-time performance
431 | 
432 | ### Best Practices
433 | 
434 | 1. **Monitor Cache Efficiency**: Aim for >80% cache hit rate
435 | 2. **Adjust Page Size**: Based on item rendering complexity
436 | 3. **Use Filtering Wisely**: Client-side filtering is efficient up to ~10k items
437 | 4. **Consider Server-side**: For very large datasets, implement server-side pagination
438 | 5. **Profile Performance**: Use React DevTools to monitor re-renders
439 | 
440 | ## Error Handling
441 | 
442 | ```typescript
443 | function RobustPaginatedList() {
444 |   const {
445 |     currentPageItems,
446 |     error,
447 |     isLoadingPage,
448 |     addToSet
449 |   } = useGunCollectionStatePaginated<TodoItem>(ref, {
450 |     pageSize: 20
451 |   });
452 | 
453 |   // Handle different error types
454 |   if (error) {
455 |     switch (error.code) {
456 |       case 'NETWORK_ERROR':
457 |         return <div>Network error. Retrying...</div>;
458 |       case 'AUTH_ERROR':
459 |         return <div>Authentication required.</div>;
460 |       default:
461 |         return <div>Error: {error.err}</div>;
462 |     }
463 |   }
464 | 
465 |   const handleAddWithErrorHandling = async (data: TodoItem) => {
466 |     try {
467 |       await addToSet(data);
468 |     } catch (error) {
469 |       // Handle operation-specific errors
470 |       if (error.code === 'QUOTA_EXCEEDED') {
471 |         alert('Storage quota exceeded');
472 |       } else {
473 |         console.error('Failed to add item:', error);
474 |       }
475 |     }
476 |   };
477 | 
478 |   return (
479 |     <div>
480 |       {isLoadingPage && <div>Loading...</div>}
481 | 
482 |       {currentPageItems.map(item => (
483 |         <div key={item.nodeID}>{item.text}</div>
484 |       ))}
485 | 
486 |       <button onClick={() => handleAddWithErrorHandling(newTodo)}>
487 |         Add Todo
488 |       </button>
489 |     </div>
490 |   );
491 | }
492 | ```
493 | 
494 | ## TypeScript Support
495 | 
496 | The hook provides comprehensive TypeScript support with full type inference:
497 | 
498 | ```typescript
499 | interface CustomItem {
500 |   title: string;
501 |   description?: string;
502 |   tags: string[];
503 |   createdAt: Date;
504 |   metadata: {
505 |     author: string;
506 |     version: number;
507 |   };
508 | }
509 | 
510 | // Full type safety
511 | const {
512 |   currentPageItems, // NodeT<CustomItem>[]
513 |   addToSet, // (data: CustomItem, nodeID?: string) => Promise<void>
514 |   updateInSet, // (nodeID: string, data: Partial<CustomItem>) => Promise<void>
515 | } = useGunCollectionStatePaginated<CustomItem>(ref, {
516 |   sortBy: 'createdAt', // Only accepts keyof CustomItem
517 |   filter: (item) => {
518 |     // item is typed as CustomItem
519 |     return item.tags.includes('important');
520 |   },
521 | });
522 | ```
523 | 


--------------------------------------------------------------------------------
/docs/useGunCollectionState.md:
--------------------------------------------------------------------------------
  1 | # useGunCollectionState
  2 | 
  3 | A hook that provides access to Gun Sets (collections) with comprehensive CRUD operations, error handling, and TypeScript support.
  4 | 
  5 | ## API Reference
  6 | 
  7 | ### Signature
  8 | 
  9 | ```typescript
 10 | useGunCollectionState<T>(ref: GunRef, opts?: Options): UseGunCollectionReturn<T>
 11 | ```
 12 | 
 13 | ### Return Type
 14 | 
 15 | ```typescript
 16 | interface UseGunCollectionReturn<T> {
 17 |   collection: Map<string, NodeT<T>> | undefined; // Raw Map collection
 18 |   items: NodeT<T>[]; // Array for easy iteration
 19 |   addToSet: (data: T, nodeID?: string) => Promise<void>; // Add item
 20 |   updateInSet: (nodeID: string, data: Partial<T>) => Promise<void>; // Update item
 21 |   removeFromSet: (nodeID: string) => Promise<void>; // Remove item
 22 |   error: GunError | null; // Error state
 23 |   isLoading: boolean; // Loading state
 24 |   count: number; // Item count
 25 | }
 26 | ```
 27 | 
 28 | ### Data Type
 29 | 
 30 | ```typescript
 31 | type NodeT<T> = T & {
 32 |   nodeID: string; // Unique identifier for each item
 33 |   [key: string]: any;
 34 | };
 35 | ```
 36 | 
 37 | ## Basic Usage
 38 | 
 39 | ### Simple Todo List
 40 | 
 41 | ```typescript
 42 | import React from 'react';
 43 | import { useGun, useGunCollectionState } from '@altrx/gundb-react-hooks';
 44 | import Gun from 'gun';
 45 | 
 46 | interface TodoItem {
 47 |   text: string;
 48 |   completed: boolean;
 49 |   createdAt: string;
 50 | }
 51 | 
 52 | export const TodoApp: React.FC = () => {
 53 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
 54 | 
 55 |   const {
 56 |     items: todos,
 57 |     addToSet: addTodo,
 58 |     updateInSet: updateTodo,
 59 |     removeFromSet: removeTodo,
 60 |     error,
 61 |     isLoading,
 62 |     count
 63 |   } = useGunCollectionState<TodoItem>(gun.get('todos'));
 64 | 
 65 |   // Handle loading state
 66 |   if (isLoading) {
 67 |     return <div>Loading todos...</div>;
 68 |   }
 69 | 
 70 |   // Handle errors
 71 |   if (error) {
 72 |     return (
 73 |       <div className="error">
 74 |         <h3>Error loading todos</h3>
 75 |         <p>{error.err}</p>
 76 |         {error.context && <small>Context: {error.context}</small>}
 77 |       </div>
 78 |     );
 79 |   }
 80 | 
 81 |   const handleAddTodo = async () => {
 82 |     try {
 83 |       await addTodo({
 84 |         text: `New todo ${Date.now()}`,
 85 |         completed: false,
 86 |         createdAt: new Date().toISOString()
 87 |       });
 88 |       console.log('Todo added successfully');
 89 |     } catch (error) {
 90 |       console.error('Failed to add todo:', error);
 91 |     }
 92 |   };
 93 | 
 94 |   const handleToggleTodo = async (todo: NodeT<TodoItem>) => {
 95 |     try {
 96 |       await updateTodo(todo.nodeID, {
 97 |         completed: !todo.completed
 98 |       });
 99 |     } catch (error) {
100 |       console.error('Failed to toggle todo:', error);
101 |     }
102 |   };
103 | 
104 |   const handleDeleteTodo = async (nodeID: string) => {
105 |     try {
106 |       await removeTodo(nodeID);
107 |     } catch (error) {
108 |       console.error('Failed to delete todo:', error);
109 |     }
110 |   };
111 | 
112 |   return (
113 |     <div>
114 |       <h1>Todo List ({count} items)</h1>
115 | 
116 |       <button onClick={handleAddTodo} className="add-button">
117 |         Add Todo
118 |       </button>
119 | 
120 |       <ul className="todo-list">
121 |         {todos.map(todo => (
122 |           <li key={todo.nodeID} className={todo.completed ? 'completed' : ''}>
123 |             <span
124 |               onClick={() => handleToggleTodo(todo)}
125 |               style={{
126 |                 textDecoration: todo.completed ? 'line-through' : 'none',
127 |                 cursor: 'pointer'
128 |               }}
129 |             >
130 |               {todo.text}
131 |             </span>
132 |             <button onClick={() => handleDeleteTodo(todo.nodeID)}>
133 |               Delete
134 |             </button>
135 |             <small>Created: {new Date(todo.createdAt).toLocaleDateString()}</small>
136 |           </li>
137 |         ))}
138 |       </ul>
139 | 
140 |       {todos.length === 0 && (
141 |         <p>No todos yet. Add one above!</p>
142 |       )}
143 |     </div>
144 |   );
145 | };
146 | ```
147 | 
148 | ## Advanced Usage
149 | 
150 | ### Real-time Chat with Authentication
151 | 
152 | ```typescript
153 | import React, { useState } from 'react';
154 | import {
155 |   useGun,
156 |   useGunCollectionState,
157 |   useGunKeyAuth,
158 |   useGunKeys
159 | } from '@altrx/gundb-react-hooks';
160 | import Gun from 'gun';
161 | import SEA from 'gun/sea';
162 | 
163 | interface ChatMessage {
164 |   text: string;
165 |   author: string;
166 |   timestamp: string;
167 |   encrypted?: boolean;
168 | }
169 | 
170 | export const ChatApp: React.FC = () => {
171 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
172 |   const appKeys = useGunKeys(SEA);
173 |   const [user, isLoggedIn, authError] = useGunKeyAuth(gun, appKeys!);
174 | 
175 |   if (authError) {
176 |     return <div>Auth Error: {authError.err}</div>;
177 |   }
178 | 
179 |   if (!appKeys || !isLoggedIn) {
180 |     return <div>Authenticating...</div>;
181 |   }
182 | 
183 |   return <ChatRoom user={user} appKeys={appKeys} />;
184 | };
185 | 
186 | const ChatRoom: React.FC<{ user: any; appKeys: any }> = ({ user, appKeys }) => {
187 |   const [messageText, setMessageText] = useState('');
188 | 
189 |   const {
190 |     items: messages,
191 |     addToSet: sendMessage,
192 |     error,
193 |     isLoading,
194 |     count
195 |   } = useGunCollectionState<ChatMessage>(
196 |     user.get('chat').get('room1'),
197 |     { appKeys, sea: SEA } // Encrypted messages
198 |   );
199 | 
200 |   const handleSendMessage = async () => {
201 |     if (!messageText.trim()) return;
202 | 
203 |     try {
204 |       await sendMessage({
205 |         text: messageText,
206 |         author: appKeys.pub.slice(0, 8), // Short public key as username
207 |         timestamp: new Date().toISOString(),
208 |         encrypted: true
209 |       });
210 |       setMessageText('');
211 |     } catch (error) {
212 |       console.error('Failed to send message:', error);
213 |     }
214 |   };
215 | 
216 |   if (isLoading) return <div>Loading chat...</div>;
217 |   if (error) return <div>Chat Error: {error.err}</div>;
218 | 
219 |   // Sort messages by timestamp
220 |   const sortedMessages = messages.sort((a, b) =>
221 |     new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
222 |   );
223 | 
224 |   return (
225 |     <div className="chat-room">
226 |       <h2>Encrypted Chat Room ({count} messages)</h2>
227 | 
228 |       <div className="messages">
229 |         {sortedMessages.map(message => (
230 |           <div key={message.nodeID} className="message">
231 |             <strong>{message.author}:</strong> {message.text}
232 |             <small>{new Date(message.timestamp).toLocaleTimeString()}</small>
233 |             {message.encrypted && <span>🔒</span>}
234 |           </div>
235 |         ))}
236 |       </div>
237 | 
238 |       <div className="message-input">
239 |         <input
240 |           type="text"
241 |           value={messageText}
242 |           onChange={(e) => setMessageText(e.target.value)}
243 |           onKeyPress={(e) => e.key === 'Enter' && handleSendMessage()}
244 |           placeholder="Type a message..."
245 |         />
246 |         <button onClick={handleSendMessage}>Send</button>
247 |       </div>
248 |     </div>
249 |   );
250 | };
251 | ```
252 | 
253 | ### Advanced Shopping Cart
254 | 
255 | ```typescript
256 | import React from 'react';
257 | import { useGunCollectionState, useGunContext } from '@altrx/gundb-react-hooks';
258 | 
259 | interface CartItem {
260 |   productId: string;
261 |   name: string;
262 |   price: number;
263 |   quantity: number;
264 |   addedAt: string;
265 | }
266 | 
267 | export const ShoppingCart: React.FC = () => {
268 |   const gun = useGunContext();
269 | 
270 |   const {
271 |     items: cartItems,
272 |     addToSet: addToCart,
273 |     updateInSet: updateCartItem,
274 |     removeFromSet: removeFromCart,
275 |     error,
276 |     isLoading,
277 |     count
278 |   } = useGunCollectionState<CartItem>(gun.get('user').get('cart'));
279 | 
280 |   // Calculate total price
281 |   const totalPrice = cartItems.reduce((total, item) =>
282 |     total + (item.price * item.quantity), 0
283 |   );
284 | 
285 |   const handleAddProduct = async (product: Omit<CartItem, 'addedAt'>) => {
286 |     try {
287 |       await addToCart({
288 |         ...product,
289 |         addedAt: new Date().toISOString()
290 |       });
291 |     } catch (error) {
292 |       console.error('Failed to add to cart:', error);
293 |     }
294 |   };
295 | 
296 |   const handleUpdateQuantity = async (nodeID: string, newQuantity: number) => {
297 |     if (newQuantity <= 0) {
298 |       await removeFromCart(nodeID);
299 |     } else {
300 |       try {
301 |         await updateCartItem(nodeID, { quantity: newQuantity });
302 |       } catch (error) {
303 |         console.error('Failed to update quantity:', error);
304 |       }
305 |     }
306 |   };
307 | 
308 |   if (isLoading) return <div>Loading cart...</div>;
309 |   if (error) return <div>Cart Error: {error.err}</div>;
310 | 
311 |   return (
312 |     <div className="shopping-cart">
313 |       <h2>Shopping Cart ({count} items)</h2>
314 | 
315 |       {cartItems.length === 0 ? (
316 |         <p>Your cart is empty</p>
317 |       ) : (
318 |         <>
319 |           <div className="cart-items">
320 |             {cartItems.map(item => (
321 |               <div key={item.nodeID} className="cart-item">
322 |                 <h4>{item.name}</h4>
323 |                 <p>Price: ${item.price}</p>
324 |                 <div className="quantity-controls">
325 |                   <button onClick={() =>
326 |                     handleUpdateQuantity(item.nodeID, item.quantity - 1)
327 |                   }>
328 |                     -
329 |                   </button>
330 |                   <span>Qty: {item.quantity}</span>
331 |                   <button onClick={() =>
332 |                     handleUpdateQuantity(item.nodeID, item.quantity + 1)
333 |                   }>
334 |                     +
335 |                   </button>
336 |                 </div>
337 |                 <p>Subtotal: ${(item.price * item.quantity).toFixed(2)}</p>
338 |                 <button onClick={() => removeFromCart(item.nodeID)}>
339 |                   Remove
340 |                 </button>
341 |               </div>
342 |             ))}
343 |           </div>
344 | 
345 |           <div className="cart-summary">
346 |             <h3>Total: ${totalPrice.toFixed(2)}</h3>
347 |             <button className="checkout-button">Checkout</button>
348 |           </div>
349 |         </>
350 |       )}
351 | 
352 |       {/* Example add product buttons */}
353 |       <div className="product-examples">
354 |         <h3>Sample Products</h3>
355 |         <button onClick={() => handleAddProduct({
356 |           productId: '1',
357 |           name: 'Coffee Mug',
358 |           price: 12.99,
359 |           quantity: 1
360 |         })}>
361 |           Add Coffee Mug ($12.99)
362 |         </button>
363 |         <button onClick={() => handleAddProduct({
364 |           productId: '2',
365 |           name: 'Notebook',
366 |           price: 8.50,
367 |           quantity: 1
368 |         })}>
369 |           Add Notebook ($8.50)
370 |         </button>
371 |       </div>
372 |     </div>
373 |   );
374 | };
375 | ```
376 | 
377 | ## Error Handling Patterns
378 | 
379 | ### Comprehensive Error Handling
380 | 
381 | ```typescript
382 | const TodoListWithErrorHandling: React.FC = () => {
383 |   const [retryCount, setRetryCount] = useState(0);
384 | 
385 |   const {
386 |     items,
387 |     addToSet,
388 |     error,
389 |     isLoading
390 |   } = useGunCollectionState<TodoItem>(ref);
391 | 
392 |   // Retry mechanism
393 |   const handleRetry = () => {
394 |     setRetryCount(prev => prev + 1);
395 |     window.location.reload(); // Simple retry
396 |   };
397 | 
398 |   // Different error handling strategies
399 |   if (error) {
400 |     if (error.context === 'useGunCollectionState connection') {
401 |       return (
402 |         <div className="connection-error">
403 |           <h3>Connection Error</h3>
404 |           <p>Unable to connect to the Gun network</p>
405 |           <button onClick={handleRetry}>Retry Connection</button>
406 |         </div>
407 |       );
408 |     }
409 | 
410 |     if (error.context?.includes('addToSet')) {
411 |       return (
412 |         <div className="operation-error">
413 |           <h3>Failed to Add Item</h3>
414 |           <p>{error.err}</p>
415 |           <button onClick={handleRetry}>Try Again</button>
416 |         </div>
417 |       );
418 |     }
419 | 
420 |     // Generic error fallback
421 |     return (
422 |       <div className="generic-error">
423 |         <h3>Something went wrong</h3>
424 |         <p>{error.err}</p>
425 |         <details>
426 |           <summary>Error Details</summary>
427 |           <p>Context: {error.context}</p>
428 |           <p>Code: {error.code}</p>
429 |           <p>Retry count: {retryCount}</p>
430 |         </details>
431 |         <button onClick={handleRetry}>Retry</button>
432 |       </div>
433 |     );
434 |   }
435 | 
436 |   return <div>{/* Normal component */}</div>;
437 | };
438 | ```
439 | 
440 | ## Migration from v0.9.x
441 | 
442 | ### Before (v0.9.x)
443 | 
444 | ```typescript
445 | const { collection, addToSet, updateInSet, removeFromSet } =
446 |   useGunCollectionState(ref);
447 | 
448 | // Manual array conversion
449 | const items = collection ? Array.from(collection.values()) : [];
450 | const count = collection?.size || 0;
451 | 
452 | // No error handling
453 | addToSet(data); // Could fail silently
454 | ```
455 | 
456 | ### After (v1.0.0)
457 | 
458 | ```typescript
459 | const {
460 |   collection,           // Still available as Map
461 |   items,               // NEW: Direct array access
462 |   addToSet,
463 |   updateInSet,
464 |   removeFromSet,
465 |   error,               // NEW: Error state
466 |   isLoading,           // NEW: Loading state
467 |   count                // NEW: Built-in count
468 | } = useGunCollectionState(ref);
469 | 
470 | // Explicit error handling
471 | if (error) {
472 |   console.error('Collection error:', error.err);
473 | }
474 | 
475 | // Use items directly (no manual conversion needed)
476 | items.map(item => <div key={item.nodeID}>{item.name}</div>)
477 | 
478 | // Async operations with error handling
479 | try {
480 |   await addToSet(data);
481 | } catch (error) {
482 |   console.error('Failed to add:', error);
483 | }
484 | ```
485 | 
486 | ## Performance Tips
487 | 
488 | ### Optimization Strategies
489 | 
490 | ```typescript
491 | import { useMemo, useCallback } from 'react';
492 | 
493 | const OptimizedCollection: React.FC = () => {
494 |   const { items, addToSet } = useGunCollectionState<TodoItem>(ref);
495 | 
496 |   // Memoize filtered/sorted data
497 |   const completedTodos = useMemo(() =>
498 |     items.filter(todo => todo.completed),
499 |     [items]
500 |   );
501 | 
502 |   const sortedTodos = useMemo(() =>
503 |     items.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()),
504 |     [items]
505 |   );
506 | 
507 |   // Memoize event handlers
508 |   const handleAddTodo = useCallback(async (text: string) => {
509 |     await addToSet({
510 |       text,
511 |       completed: false,
512 |       createdAt: new Date().toISOString()
513 |     });
514 |   }, [addToSet]);
515 | 
516 |   return (
517 |     <div>
518 |       <h3>Completed: {completedTodos.length}</h3>
519 |       {sortedTodos.map(todo => (
520 |         <TodoItem key={todo.nodeID} todo={todo} onAdd={handleAddTodo} />
521 |       ))}
522 |     </div>
523 |   );
524 | };
525 | ```
526 | 
527 | ## Best Practices
528 | 
529 | 1. **Use TypeScript interfaces** for your collection item types
530 | 2. **Handle errors explicitly** - Always check the `error` state
531 | 3. **Show loading states** - Use `isLoading` for better UX
532 | 4. **Use `items` for iteration** - More convenient than Map conversion
533 | 5. **Validate inputs** - Check data before calling `addToSet`/`updateInSet`
534 | 6. **Handle async operations** - Use try-catch with CRUD operations
535 | 7. **Optimize with memoization** - Use `useMemo` for expensive filtering/sorting
536 | 8. **Monitor collection size** - Use the built-in `count` property
537 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # GunDB React Hooks
  2 | 
  3 | [![npm version](https://badge.fury.io/js/%40altrx%2Fgundb-react-hooks.svg)](https://badge.fury.io/js/%40altrx%2Fgundb-react-hooks)
  4 | [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org)
  5 | [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  6 | 
  7 | Type-safe, performant GunDB hooks for React/Preact with comprehensive error handling, loading states, and debugging utilities.
  8 | 
  9 | ## Live Example
 10 | https://gun-react-todoapp.vercel.app/
 11 | 
 12 | Repo available at: https://github.com/alterx/gun-react-todoapp
 13 | 
 14 | ## Features
 15 | 
 16 | - **Type-safe** - Comprehensive TypeScript definitions
 17 | - **Performant** - Optimized with memoization and proper cleanup
 18 | - **Reliable** - Built-in error handling and loading states
 19 | - **Developer-friendly** - Debug utilities and development warnings
 20 | - **Zero memory leaks** - Proper listener cleanup and memory management
 21 | - **React & Preact** - Support for both frameworks
 22 | - **Real-time** - Live updates with efficient debouncing
 23 | - **Authentication** - Built-in auth provider with key management and storage
 24 | - **Pagination** - High-performance paginated collections with smart caching
 25 | 
 26 | ## Quick Start
 27 | 
 28 | ### Installing
 29 | 
 30 | ```bash
 31 | npm install @altrx/gundb-react-hooks
 32 | # or
 33 | yarn add @altrx/gundb-react-hooks
 34 | # or
 35 | pnpm add @altrx/gundb-react-hooks
 36 | ```
 37 | 
 38 | ### Basic Usage
 39 | 
 40 | ```typescript
 41 | import React from 'react';
 42 | import Gun from 'gun';
 43 | import { useGun, useGunState, useGunCollectionState } from '@altrx/gundb-react-hooks';
 44 | 
 45 | function App() {
 46 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
 47 | 
 48 |   return <UserProfile gun={gun} />;
 49 | }
 50 | 
 51 | function UserProfile({ gun }) {
 52 |   const {
 53 |     fields: profile,
 54 |     put,
 55 |     error,
 56 |     isLoading
 57 |   } = useGunState(gun.get('user').get('profile'));
 58 | 
 59 |   if (isLoading) return <div>Loading...</div>;
 60 |   if (error) return <div>Error: {error.err}</div>;
 61 | 
 62 |   return (
 63 |     <div>
 64 |       <h1>{profile.name || 'Anonymous'}</h1>
 65 |       <button onClick={() => put({ name: 'John Doe' })}>
 66 |         Update Name
 67 |       </button>
 68 |     </div>
 69 |   );
 70 | }
 71 | ```
 72 | 
 73 | ### With Authentication
 74 | 
 75 | ```typescript
 76 | import { AuthProvider, useAuth } from '@altrx/gundb-react-hooks';
 77 | 
 78 | function App() {
 79 |   return (
 80 |     <AuthProvider
 81 |       Gun={Gun}
 82 |       sea={Gun.SEA}
 83 |       storage={localStorage}
 84 |       gunOpts={{ peers: ['http://localhost:8765/gun'] }}
 85 |     >
 86 |       <AuthenticatedApp />
 87 |     </AuthProvider>
 88 |   );
 89 | }
 90 | 
 91 | function AuthenticatedApp() {
 92 |   const { user, login, logout, isLoggedIn, appKeys } = useAuth();
 93 | 
 94 |   const { fields: profile, put } = useGunState(
 95 |     user?.get('profile'),
 96 |     { appKeys }
 97 |   );
 98 | 
 99 |   if (!isLoggedIn) {
100 |     return (
101 |       <div>
102 |         <button onClick={() => login()}>Login</button>
103 |       </div>
104 |     );
105 |   }
106 | 
107 |   return (
108 |     <div>
109 |       <h1>Welcome, {profile.name || 'User'}!</h1>
110 |       <input
111 |         value={profile.name || ''}
112 |         onChange={(e) => put({ name: e.target.value })}
113 |         placeholder="Enter your name"
114 |       />
115 |       <button onClick={() => logout()}>Logout</button>
116 |     </div>
117 |   );
118 | }
119 | ```
120 | 
121 | ### With Error Handling & TypeScript
122 | 
123 | ```typescript
124 | interface UserProfile {
125 |   name: string;
126 |   email: string;
127 |   avatar?: string;
128 | }
129 | 
130 | interface TodoItem {
131 |   text: string;
132 |   completed: boolean;
133 |   createdAt: string;
134 | }
135 | 
136 | function TypeSafeApp() {
137 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
138 | 
139 |   // Type-safe user profile
140 |   const {
141 |     fields: profile,
142 |     put: updateProfile,
143 |     error: profileError,
144 |     isLoading: profileLoading
145 |   } = useGunState<UserProfile>(gun.get('user').get('profile'));
146 | 
147 |   // Type-safe todo collection with pagination
148 |   const {
149 |     currentPageItems: todos,
150 |     addToSet: addTodo,
151 |     removeFromSet: removeTodo,
152 |     updateInSet: updateTodo,
153 |     error: todosError,
154 |     totalItems: todoCount,
155 |     currentPage,
156 |     totalPages,
157 |     nextPage,
158 |     prevPage,
159 |     pageSize,
160 |     setPageSize
161 |   } = useGunCollectionStatePaginated<TodoItem>(gun.get('todos'), {
162 |     pageSize: 10,
163 |     sortBy: 'createdAt',
164 |     sortOrder: 'desc',
165 |     preloadPages: 1
166 |   });
167 | 
168 |   const handleAddTodo = async () => {
169 |     try {
170 |       await addTodo({
171 |         text: 'New todo',
172 |         completed: false,
173 |         createdAt: new Date().toISOString()
174 |       });
175 |     } catch (error) {
176 |       console.error('Failed to add todo:', error);
177 |     }
178 |   };
179 | 
180 |   if (profileError || todosError) {
181 |     return <ErrorComponent error={profileError || todosError} />;
182 |   }
183 | 
184 |   return (
185 |     <div>
186 |       <h1>{profile.name}'s Todos ({todoCount})</h1>
187 | 
188 |       {/* Pagination Controls */}
189 |       <div>
190 |         <span>Page {currentPage + 1} of {totalPages}</span>
191 |         <select value={pageSize} onChange={(e) => setPageSize(Number(e.target.value))}>
192 |           <option value={5}>5 per page</option>
193 |           <option value={10}>10 per page</option>
194 |           <option value={20}>20 per page</option>
195 |         </select>
196 |       </div>
197 | 
198 |       {/* Todo Items */}
199 |       {todos.map(todo => (
200 |         <TodoItem
201 |           key={todo.nodeID}
202 |           todo={todo}
203 |           onToggle={() => updateTodo(todo.nodeID, { completed: !todo.completed })}
204 |           onRemove={() => removeTodo(todo.nodeID)}
205 |         />
206 |       ))}
207 | 
208 |       {/* Pagination Navigation */}
209 |       <div>
210 |         <button onClick={prevPage} disabled={currentPage === 0}>
211 |           Previous
212 |         </button>
213 |         <button onClick={nextPage} disabled={currentPage >= totalPages - 1}>
214 |           Next
215 |         </button>
216 |       </div>
217 | 
218 |       <button onClick={handleAddTodo}>Add Todo</button>
219 |     </div>
220 |   );
221 | }
222 | ```
223 | 
224 | ## API Reference
225 | 
226 | ## API Reference
227 | 
228 | ### Core Hooks
229 | 
230 | #### `useGun(Gun, options)`
231 | 
232 | Initialize a Gun instance.
233 | 
234 | ```typescript
235 | const gun = useGun(Gun, {
236 |   peers: ['http://localhost:8765/gun'],
237 |   localStorage: true,
238 | });
239 | ```
240 | 
241 | #### `useGunState<T>(ref, options)`
242 | 
243 | Manage state for a Gun node with error handling and loading states.
244 | 
245 | ```typescript
246 | const {
247 |   fields, // T: The current state
248 |   put, // (data: Partial<T>) => Promise<void>
249 |   remove, // (field: string) => Promise<void>
250 |   error, // GunError | null
251 |   isLoading, // boolean
252 |   isConnected, // boolean
253 | } = useGunState<T>(ref, options);
254 | ```
255 | 
256 | #### `useGunCollectionState<T>(ref, options)`
257 | 
258 | Manage collections (Sets) with comprehensive CRUD operations.
259 | 
260 | ```typescript
261 | const {
262 |   collection, // Map<string, NodeT<T>>
263 |   items, // NodeT<T>[] - Array for easy iteration
264 |   addToSet, // (data: T, nodeID?: string) => Promise<void>
265 |   updateInSet, // (nodeID: string, data: Partial<T>) => Promise<void>
266 |   removeFromSet, // (nodeID: string) => Promise<void>
267 |   error, // GunError | null
268 |   isLoading, // boolean
269 |   count, // number
270 | } = useGunCollectionState<T>(ref, options);
271 | ```
272 | 
273 | #### `useGunCollectionStatePaginated<T>(ref, options)`
274 | 
275 | High-performance paginated collections with smart caching and real-time updates.
276 | 
277 | ```typescript
278 | const {
279 |   currentPageItems, // NodeT<T>[] - Current page items
280 |   currentPage, // number - Current page index (0-based)
281 |   totalPages, // number - Total number of pages
282 |   pageSize, // number - Items per page
283 |   setPageSize, // (size: number) => void
284 |   nextPage, // () => void
285 |   prevPage, // () => void
286 |   goToPage, // (page: number) => void
287 |   hasNextPage, // boolean
288 |   hasPrevPage, // boolean
289 |   isLoadingPage, // boolean
290 |   totalItems, // number - Total items in collection
291 |   // ... all useGunCollectionState methods
292 |   addToSet, // (data: T, nodeID?: string) => Promise<void>
293 |   updateInSet, // (nodeID: string, data: Partial<T>) => Promise<void>
294 |   removeFromSet, // (nodeID: string) => Promise<void>
295 |   error, // GunError | null
296 |   preloadedPages, // Set<number> - Cached pages
297 | } = useGunCollectionStatePaginated<T>(ref, options);
298 | ```
299 | 
300 | #### `useGunKeyAuth(gun, keys, triggerAuth?)`
301 | 
302 | Handle authentication with key pairs.
303 | 
304 | ```typescript
305 | const [
306 |   namespacedGraph, // IGunUserReference
307 |   isLoggedIn, // boolean
308 |   authError, // GunError | null
309 | ] = useGunKeyAuth(gun, keyPair, true);
310 | ```
311 | 
312 | #### `useGunKeys(sea, existingKeys?)`
313 | 
314 | Generate or use existing key pairs.
315 | 
316 | ```typescript
317 | const keyPair = useGunKeys(SEA, existingKeys);
318 | ```
319 | 
320 | ### Utility Hooks
321 | 
322 | #### `useGunDebug(ref, label, enabled?)`
323 | 
324 | Debug hook for development - logs all updates.
325 | 
326 | ```typescript
327 | // Only active in development
328 | useGunDebug(userRef, 'UserProfile', process.env.NODE_ENV === 'development');
329 | ```
330 | 
331 | #### `useGunConnection(ref)`
332 | 
333 | Monitor connection status and health.
334 | 
335 | ```typescript
336 | const { isConnected, lastSeen, error } = useGunConnection(gun);
337 | ```
338 | 
339 | ### Context Providers
340 | 
341 | #### `GunProvider`
342 | 
343 | Provide Gun instance through React context.
344 | 
345 | ```typescript
346 | <GunProvider gun={Gun} options={{ peers: ['http://localhost:8765/gun'] }}>
347 |   <App />
348 | </GunProvider>
349 | ```
350 | 
351 | #### `useGunContext()`
352 | 
353 | Access Gun instance from context.
354 | 
355 | ```typescript
356 | const gun = useGunContext();
357 | ```
358 | 
359 | #### `AuthProvider`
360 | 
361 | Comprehensive authentication provider with key management.
362 | 
363 | ```typescript
364 | <AuthProvider
365 |   Gun={Gun}
366 |   sea={Gun.SEA}
367 |   storage={localStorage}
368 |   gunOpts={{ peers: ['http://localhost:8765/gun'] }}
369 | >
370 |   <App />
371 | </AuthProvider>
372 | ```
373 | 
374 | #### `useAuth()`
375 | 
376 | Access authentication state and methods.
377 | 
378 | ```typescript
379 | const {
380 |   user, // IGunUserReference
381 |   login, // (keys?: KeyPair) => void
382 |   logout, // (callback?: () => void) => void
383 |   isLoggedIn, // boolean
384 |   appKeys, // KeyPair | undefined
385 |   gun, // IGunChainReference
386 | } = useAuth();
387 | ```
388 | 
389 | ### Types
390 | 
391 | ```typescript
392 | interface GunError {
393 |   err: string;
394 |   code?: string | number;
395 |   context?: string;
396 | }
397 | 
398 | interface NodeData<T> {
399 |   nodeID: string;
400 |   // ... your data
401 | }
402 | 
403 | interface UseGunStateReturn<T> {
404 |   fields: T;
405 |   put: (data: Partial<T>) => Promise<void>;
406 |   remove: (field: string) => Promise<void>;
407 |   error: GunError | null;
408 |   isLoading: boolean;
409 |   isConnected: boolean;
410 | }
411 | ```
412 | 
413 | ## Advanced Usage
414 | 
415 | ### Error Handling Patterns
416 | 
417 | ```typescript
418 | function MyComponent() {
419 |   const { fields, put, error } = useGunState(ref);
420 | 
421 |   // Global error handling
422 |   if (error) {
423 |     return <ErrorBoundary error={error} />;
424 |   }
425 | 
426 |   // Operation-specific error handling
427 |   const handleSave = async () => {
428 |     try {
429 |       await put(data);
430 |       showSuccessMessage();
431 |     } catch (error) {
432 |       showErrorMessage(error.err);
433 |     }
434 |   };
435 | }
436 | ```
437 | 
438 | ### Development Debugging
439 | 
440 | ```typescript
441 | function DebuggedComponent() {
442 |   const gun = useGunContext();
443 |   const userRef = gun.user().get('profile');
444 | 
445 |   // Debug all updates in development
446 |   useGunDebug(userRef, 'UserProfile');
447 | 
448 |   const { fields } = useGunState(userRef);
449 |   return <div>{fields.name}</div>;
450 | }
451 | ```
452 | 
453 | ### Performance Optimization
454 | 
455 | ```typescript
456 | // Memoize expensive operations
457 | const expensiveData = useMemo(() => {
458 |   return items
459 |     .filter((item) => item.category === selectedCategory)
460 |     .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
461 | }, [items, selectedCategory]);
462 | 
463 | // Use callback for event handlers
464 | const handleAddItem = useCallback(
465 |   async (item) => {
466 |     await addToSet(item);
467 |   },
468 |   [addToSet],
469 | );
470 | ```
471 | 
472 | ## Migration from v0.9.x
473 | 
474 | ### New Pagination Hook
475 | 
476 | v1.0.0 introduces `useGunCollectionStatePaginated` for high-performance collection management:
477 | 
478 | ```typescript
479 | // Before: Basic collection
480 | const { items, addToSet } = useGunCollectionState(ref);
481 | 
482 | // After: Paginated with optimization
483 | const { currentPageItems, addToSet, nextPage, totalPages } =
484 |   useGunCollectionStatePaginated(ref, {
485 |     pageSize: 20,
486 |     sortBy: 'createdAt',
487 |     preloadPages: 2,
488 |   });
489 | ```
490 | 
491 | ### Performance Benefits
492 | 
493 | - **Memory Efficient**: Only loads current page + preloaded pages
494 | - **Smart Caching**: 5-minute page cache with automatic invalidation
495 | - **Real-time Updates**: Debounced live synchronization
496 | - **Type Safety**: Full TypeScript support with inference
497 | 
498 | For detailed migration instructions and compatibility information, see the detailed documentation for each hook.
499 | 
500 | ## Development & Testing
501 | 
502 | ### Debug Mode
503 | 
504 | ```typescript
505 | // Enable debug logging for specific components
506 | useGunDebug(ref, 'ComponentName', true);
507 | 
508 | // Connection monitoring
509 | const { isConnected, lastSeen } = useGunConnection(gun);
510 | ```
511 | 
512 | ### Error Boundaries
513 | 
514 | ```typescript
515 | function AppWithErrorBoundary() {
516 |   return (
517 |     <ErrorBoundary>
518 |       <GunProvider gun={Gun} options={opts}>
519 |         <App />
520 |       </GunProvider>
521 |     </ErrorBoundary>
522 |   );
523 | }
524 | ```
525 | 
526 | ## Examples & Documentation
527 | 
528 | - [useGun](https://github.com/alterx/gundb-react-hooks/blob/master/docs/useGun.md)
529 | - [useGunNamespace](https://github.com/alterx/gundb-react-hooks/blob/master/docs/useGunNamespace.md)
530 | - [useGunKeyAuth](https://github.com/alterx/gundb-react-hooks/blob/master/docs/useGunKeyAuth.md)
531 | - [useGunKeys](https://github.com/alterx/gundb-react-hooks/blob/master/docs/useGunKeys.md)
532 | - [useGunOnNodeUpdated](https://github.com/alterx/gundb-react-hooks/blob/master/docs/useGunOnNodeUpdated.md)
533 | - [useGunState](https://github.com/alterx/gundb-react-hooks/blob/master/docs/useGunState.md)
534 | - [useGunCollectionState](https://github.com/alterx/gundb-react-hooks/blob/master/docs/useGunCollectionState.md)
535 | - [useGunCollectionStatePaginated](https://github.com/alterx/gundb-react-hooks/blob/master/docs/useGunCollectionStatePaginated.md)
536 | - [useAuth](https://github.com/alterx/gundb-react-hooks/blob/master/docs/useAuth.md)
537 | - [AuthProvider](https://github.com/alterx/gundb-react-hooks/blob/master/docs/AuthProvider.md)
538 | 
539 | ## Contributing
540 | 
541 | We welcome contributions! Please see our contributing guidelines and:
542 | 
543 | 1. **Fork the repository**
544 | 2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
545 | 3. **Add tests** for your changes
546 | 4. **Ensure type safety** with TypeScript
547 | 5. **Submit a pull request**
548 | 
549 | ## License
550 | 
551 | Licensed under [MIT](https://github.com/alterx/gundb-react-hooks/blob/master/LICENSE.md).
552 | 
553 | ## Acknowledgments
554 | 
555 | - [GunDB](https://gun.eco/) for the decentralized database
556 | - [React](https://reactjs.org/) and [Preact](https://preactjs.com/) communities
557 | 


--------------------------------------------------------------------------------
/docs/useGunOnNodeUpdated.md:
--------------------------------------------------------------------------------
  1 | # useGunOnNodeUpdated
  2 | 
  3 | A hook that subscribes to Gun node updates with comprehensive error handling, dependency tracking, and cleanup management.
  4 | 
  5 | ## Overview
  6 | 
  7 | `useGunOnNodeUpdated` provides real-time subscription functionality for GunDB nodes. It manages subscriptions automatically, handles cleanup to prevent memory leaks, and offers comprehensive error handling for robust real-time applications.
  8 | 
  9 | ## API Reference
 10 | 
 11 | ### Signature
 12 | 
 13 | ```typescript
 14 | useGunOnNodeUpdated<T>(
 15 |   node: IGunReference,
 16 |   dependencies: any[],
 17 |   onUpdate: (data: T, key?: string, msg?: any, ev?: any) => void,
 18 |   onCleanup?: () => void
 19 | ): void
 20 | ```
 21 | 
 22 | ### Parameters
 23 | 
 24 | - `node` - Gun node reference to subscribe to
 25 | - `dependencies` - Array of dependencies that trigger re-subscription
 26 | - `onUpdate` - Callback function called when node updates
 27 | - `onCleanup` - Optional cleanup function called when subscription ends
 28 | 
 29 | ### Update Callback Parameters
 30 | 
 31 | ```typescript
 32 | onUpdate: (
 33 |   data: T,           // Updated data
 34 |   key?: string,      // Node key
 35 |   msg?: any,         // Gun message object
 36 |   ev?: any          // Event object
 37 | ) => void
 38 | ```
 39 | 
 40 | ## Basic Usage
 41 | 
 42 | ### Simple Node Subscription
 43 | 
 44 | ```typescript
 45 | import React, { useState } from 'react';
 46 | import { useGun, useGunOnNodeUpdated, useGunState } from '@altrx/gundb-react-hooks';
 47 | import Gun from 'gun';
 48 | 
 49 | interface UserProfile {
 50 |   name: string;
 51 |   status: string;
 52 |   lastSeen: string;
 53 | }
 54 | 
 55 | export const UserProfileWatcher: React.FC = () => {
 56 |   const [userId] = useState('user_12345');
 57 |   const [updates, setUpdates] = useState<any[]>([]);
 58 | 
 59 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
 60 |   const userNode = gun.get('users').get(userId);
 61 | 
 62 |   // Subscribe to user profile updates
 63 |   useGunOnNodeUpdated<UserProfile>(
 64 |     userNode,
 65 |     [userId], // Re-subscribe when userId changes
 66 |     (data, key, msg, ev) => {
 67 |       console.log('User profile updated:', data);
 68 | 
 69 |       // Track all updates
 70 |       setUpdates(prev => [{
 71 |         timestamp: new Date().toISOString(),
 72 |         data,
 73 |         key,
 74 |         type: 'profile_update'
 75 |       }, ...prev.slice(0, 9)]); // Keep last 10 updates
 76 |     },
 77 |     () => {
 78 |       console.log('User profile subscription cleaned up');
 79 |     }
 80 |   );
 81 | 
 82 |   const { fields: currentProfile, put: updateProfile } = useGunState<UserProfile>(userNode);
 83 | 
 84 |   const simulateUpdate = () => {
 85 |     updateProfile({
 86 |       name: 'John Doe',
 87 |       status: 'online',
 88 |       lastSeen: new Date().toISOString()
 89 |     });
 90 |   };
 91 | 
 92 |   return (
 93 |     <div className="user-profile-watcher">
 94 |       <h3>User Profile Watcher</h3>
 95 | 
 96 |       <div className="current-profile">
 97 |         <h4>Current Profile:</h4>
 98 |         <pre>{JSON.stringify(currentProfile, null, 2)}</pre>
 99 |         <button onClick={simulateUpdate}>
100 |           Simulate Profile Update
101 |         </button>
102 |       </div>
103 | 
104 |       <div className="update-log">
105 |         <h4>Update Log ({updates.length}/10):</h4>
106 |         {updates.map((update, index) => (
107 |           <div key={index} className="update-entry">
108 |             <p><strong>Time:</strong> {new Date(update.timestamp).toLocaleTimeString()}</p>
109 |             <p><strong>Data:</strong> {JSON.stringify(update.data, null, 2)}</p>
110 |             {update.key && <p><strong>Key:</strong> {update.key}</p>}
111 |           </div>
112 |         ))}
113 |       </div>
114 |     </div>
115 |   );
116 | };
117 | ```
118 | 
119 | ### Multi-Node Subscription
120 | 
121 | ```typescript
122 | import React, { useState, useCallback } from 'react';
123 | import { useGun, useGunOnNodeUpdated } from '@altrx/gundb-react-hooks';
124 | 
125 | interface ChatMessage {
126 |   id: string;
127 |   user: string;
128 |   message: string;
129 |   timestamp: string;
130 | }
131 | 
132 | export const MultiChatWatcher: React.FC = () => {
133 |   const [activeRooms, setActiveRooms] = useState<string[]>(['general', 'tech', 'random']);
134 |   const [roomUpdates, setRoomUpdates] = useState<{[room: string]: ChatMessage[]}>({});
135 | 
136 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
137 | 
138 |   // Subscribe to each chat room
139 |   activeRooms.forEach(roomId => {
140 |     const roomNode = gun.get('chat').get(roomId);
141 | 
142 |     useGunOnNodeUpdated<ChatMessage>(
143 |       roomNode,
144 |       [roomId, gun], // Re-subscribe when room or gun changes
145 |       useCallback((data: ChatMessage, key?: string) => {
146 |         if (data && key) {
147 |           setRoomUpdates(prev => ({
148 |             ...prev,
149 |             [roomId]: [
150 |               { ...data, id: key },
151 |               ...(prev[roomId] || []).slice(0, 19) // Keep last 20 messages
152 |             ]
153 |           }));
154 |         }
155 |       }, [roomId]),
156 |       useCallback(() => {
157 |         console.log(`Unsubscribed from room: ${roomId}`);
158 |       }, [roomId])
159 |     );
160 |   });
161 | 
162 |   const addRoom = () => {
163 |     const newRoom = prompt('Enter room name:');
164 |     if (newRoom && !activeRooms.includes(newRoom)) {
165 |       setActiveRooms(prev => [...prev, newRoom]);
166 |     }
167 |   };
168 | 
169 |   const removeRoom = (roomId: string) => {
170 |     setActiveRooms(prev => prev.filter(id => id !== roomId));
171 |     setRoomUpdates(prev => {
172 |       const updated = { ...prev };
173 |       delete updated[roomId];
174 |       return updated;
175 |     });
176 |   };
177 | 
178 |   return (
179 |     <div className="multi-chat-watcher">
180 |       <h3>Multi-Chat Room Watcher</h3>
181 | 
182 |       <div className="room-controls">
183 |         <button onClick={addRoom}>➕ Add Room</button>
184 |       </div>
185 | 
186 |       <div className="chat-rooms">
187 |         {activeRooms.map(roomId => (
188 |           <div key={roomId} className="chat-room">
189 |             <div className="room-header">
190 |               <h4>#{roomId}</h4>
191 |               <span className="message-count">
192 |                 {roomUpdates[roomId]?.length || 0} messages
193 |               </span>
194 |               <button onClick={() => removeRoom(roomId)}>❌</button>
195 |             </div>
196 | 
197 |             <div className="room-messages">
198 |               {(roomUpdates[roomId] || []).map((msg, index) => (
199 |                 <div key={index} className="message">
200 |                   <strong>{msg.user}:</strong> {msg.message}
201 |                   <small> - {new Date(msg.timestamp).toLocaleTimeString()}</small>
202 |                 </div>
203 |               ))}
204 |             </div>
205 |           </div>
206 |         ))}
207 |       </div>
208 |     </div>
209 |   );
210 | };
211 | ```
212 | 
213 | ## Advanced Usage
214 | 
215 | ### Conditional Subscriptions
216 | 
217 | ```typescript
218 | import React, { useState } from 'react';
219 | import { useGun, useGunOnNodeUpdated, useGunKeyAuth, useGunKeys } from '@altrx/gundb-react-hooks';
220 | import SEA from 'gun/sea';
221 | 
222 | export const ConditionalSubscriptionExample: React.FC = () => {
223 |   const [isMonitoring, setIsMonitoring] = useState(false);
224 |   const [isAuthenticated, setIsAuthenticated] = useState(false);
225 |   const [notifications, setNotifications] = useState<any[]>([]);
226 | 
227 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
228 |   const appKeys = useGunKeys(SEA);
229 |   const [user, isLoggedIn] = useGunKeyAuth(gun, appKeys!);
230 | 
231 |   // Only subscribe when authenticated and monitoring is enabled
232 |   const shouldSubscribe = isLoggedIn && isMonitoring && appKeys;
233 | 
234 |   if (shouldSubscribe) {
235 |     // Subscribe to user's notifications
236 |     useGunOnNodeUpdated(
237 |       user.get('notifications'),
238 |       [isLoggedIn, isMonitoring, appKeys], // Dependencies control subscription
239 |       (data, key) => {
240 |         if (data && key) {
241 |           setNotifications(prev => [{
242 |             id: key,
243 |             ...data,
244 |             receivedAt: new Date().toISOString()
245 |           }, ...prev.slice(0, 49)]); // Keep last 50 notifications
246 |         }
247 |       },
248 |       () => {
249 |         console.log('Notification subscription cleaned up');
250 |         setNotifications([]); // Clear notifications on cleanup
251 |       }
252 |     );
253 | 
254 |     // Subscribe to global announcements
255 |     useGunOnNodeUpdated(
256 |       gun.get('announcements'),
257 |       [isLoggedIn, isMonitoring],
258 |       (data, key) => {
259 |         if (data && key) {
260 |           // Show global announcements as special notifications
261 |           setNotifications(prev => [{
262 |             id: key,
263 |             ...data,
264 |             type: 'announcement',
265 |             receivedAt: new Date().toISOString()
266 |           }, ...prev]);
267 |         }
268 |       }
269 |     );
270 |   }
271 | 
272 |   if (!appKeys) {
273 |     return <div>🔑 Generating keys...</div>;
274 |   }
275 | 
276 |   if (!isLoggedIn) {
277 |     return (
278 |       <div className="auth-required">
279 |         <h3>🔐 Authentication Required</h3>
280 |         <p>Please log in to access notifications</p>
281 |       </div>
282 |     );
283 |   }
284 | 
285 |   return (
286 |     <div className="conditional-subscription">
287 |       <h3>🔔 Notification Monitor</h3>
288 | 
289 |       <div className="monitor-controls">
290 |         <label>
291 |           <input
292 |             type="checkbox"
293 |             checked={isMonitoring}
294 |             onChange={(e) => setIsMonitoring(e.target.checked)}
295 |           />
296 |           Enable Real-time Monitoring
297 |         </label>
298 |       </div>
299 | 
300 |       <div className="subscription-status">
301 |         <p><strong>Status:</strong>
302 |           {shouldSubscribe ? 'Monitoring Active' : 'Monitoring Disabled'}
303 |         </p>
304 |         <p><strong>Notifications:</strong> {notifications.length}</p>
305 |       </div>
306 | 
307 |       {isMonitoring && (
308 |         <div className="notifications">
309 |           <h4>📬 Live Notifications:</h4>
310 |           {notifications.length === 0 ? (
311 |             <p>No notifications yet...</p>
312 |           ) : (
313 |             notifications.map((notif, index) => (
314 |               <div
315 |                 key={index}
316 |                 className={`notification ${notif.type === 'announcement' ? 'announcement' : ''}`}
317 |               >
318 |                 <div className="notif-header">
319 |                   <span className="notif-type">
320 |                     {notif.type === 'announcement' ? '📢' : '🔔'}
321 |                   </span>
322 |                   <span className="notif-time">
323 |                     {new Date(notif.receivedAt).toLocaleTimeString()}
324 |                   </span>
325 |                 </div>
326 |                 <div className="notif-content">
327 |                   {JSON.stringify(notif, null, 2)}
328 |                 </div>
329 |               </div>
330 |             ))
331 |           )}
332 |         </div>
333 |       )}
334 | 
335 |       <div className="test-controls">
336 |         <button onClick={() => {
337 |           if (user && isMonitoring) {
338 |             user.get('notifications').set({
339 |               message: 'Test notification',
340 |               type: 'info',
341 |               timestamp: new Date().toISOString()
342 |             });
343 |           }
344 |         }}>
345 |           Send Test Notification
346 |         </button>
347 |       </div>
348 |     </div>
349 |   );
350 | };
351 | ```
352 | 
353 | ## Error Handling
354 | 
355 | ### Robust Error Management
356 | 
357 | ```typescript
358 | import React, { useState, useCallback } from 'react';
359 | import { useGun, useGunOnNodeUpdated } from '@altrx/gundb-react-hooks';
360 | 
361 | export const RobustSubscriptionExample: React.FC = () => {
362 |   const [subscriptionStats, setSubscriptionStats] = useState({
363 |     updates: 0,
364 |     errors: 0,
365 |     lastUpdate: null as Date | null,
366 |     lastError: null as string | null
367 |   });
368 | 
369 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
370 |   const dataNode = gun.get('monitoring_test');
371 | 
372 |   const handleUpdate = useCallback((data: any, key?: string, msg?: any, ev?: any) => {
373 |     try {
374 |       console.log('Update received:', { data, key, msg, ev });
375 | 
376 |       setSubscriptionStats(prev => ({
377 |         ...prev,
378 |         updates: prev.updates + 1,
379 |         lastUpdate: new Date(),
380 |         lastError: null
381 |       }));
382 | 
383 |       if (data && typeof data === 'object') {
384 |         console.log('Valid data processed:', data);
385 |       } else {
386 |         throw new Error('Invalid data format received');
387 |       }
388 | 
389 |     } catch (error) {
390 |       console.error('Error processing update:', error);
391 | 
392 |       setSubscriptionStats(prev => ({
393 |         ...prev,
394 |         errors: prev.errors + 1,
395 |         lastError: error instanceof Error ? error.message : 'Unknown error'
396 |       }));
397 |     }
398 |   }, []);
399 | 
400 |   useGunOnNodeUpdated(
401 |     dataNode,
402 |     [gun],
403 |     handleUpdate,
404 |     useCallback(() => {
405 |       console.log('Subscription cleanup executed');
406 |       setSubscriptionStats({
407 |         updates: 0,
408 |         errors: 0,
409 |         lastUpdate: null,
410 |         lastError: null
411 |       });
412 |     }, [])
413 |   );
414 | 
415 |   return (
416 |     <div>
417 |       <h3>Subscription Statistics</h3>
418 |       <p>Updates: {subscriptionStats.updates}</p>
419 |       <p>Errors: {subscriptionStats.errors}</p>
420 |       {subscriptionStats.lastError && (
421 |         <p>Last Error: {subscriptionStats.lastError}</p>
422 |       )}
423 |     </div>
424 |   );
425 | };
426 | ```
427 | 
428 | ## Migration from v0.9.x
429 | 
430 | ### Before (v0.9.x)
431 | 
432 | ```typescript
433 | // Basic subscription without comprehensive error handling
434 | useGunOnNodeUpdated(
435 |   user,
436 |   { appKeys },
437 |   (update) => {
438 |     // Handle update
439 |   },
440 |   () => {
441 |     // Basic cleanup
442 |   },
443 | );
444 | ```
445 | 
446 | ### After (v1.0.0)
447 | 
448 | ```typescript
449 | // Enhanced subscription with proper dependency tracking and error handling
450 | useGunOnNodeUpdated<UserData>(
451 |   user,
452 |   [appKeys, isLoggedIn], // Proper dependency array
453 |   useCallback(
454 |     (data: UserData, key?: string, msg?: any, ev?: any) => {
455 |       try {
456 |         // Type-safe update handling
457 |         if (data && isValidUserData(data)) {
458 |           handleUserUpdate(data);
459 |         }
460 |       } catch (error) {
461 |         console.error('Update processing error:', error);
462 |       }
463 |     },
464 |     [handleUserUpdate],
465 |   ),
466 |   useCallback(() => {
467 |     // Comprehensive cleanup
468 |     console.log('User subscription cleaned up');
469 |     clearUserCache();
470 |   }, [clearUserCache]),
471 | );
472 | ```
473 | 
474 | ## Best Practices
475 | 
476 | 1. **Dependency Management** - Include all relevant dependencies in the dependency array
477 | 2. **Error Handling** - Always wrap update logic in try-catch blocks
478 | 3. **Cleanup** - Implement proper cleanup to prevent memory leaks
479 | 4. **Performance** - Use `useCallback` for update and cleanup functions
480 | 5. **Type Safety** - Use TypeScript generics for type-safe updates
481 | 6. **Validation** - Validate incoming data before processing
482 | 7. **Monitoring** - Track subscription health and performance
483 | 8. **Conditional Subscriptions** - Only subscribe when necessary
484 | 
485 | ## Common Use Cases
486 | 
487 | 1. **Real-time Chat** - Subscribe to chat room updates
488 | 2. **Live Data Feeds** - Monitor data streams and updates
489 | 3. **User Presence** - Track user online/offline status
490 | 4. **Notifications** - Real-time notification delivery
491 | 5. **Collaborative Editing** - Document change synchronization
492 | 6. **Gaming** - Real-time game state updates
493 | 7. **Monitoring** - System health and metrics tracking
494 | 8. **Social Feeds** - Live social media updates
495 | 
496 | ## Performance Considerations
497 | 
498 | - **Memory Management**: Automatic cleanup prevents memory leaks
499 | - **Re-subscription**: Dependencies control when to re-subscribe
500 | - **Update Frequency**: Consider throttling high-frequency updates
501 | - **Data Validation**: Validate data early to prevent processing errors
502 | - **Batch Updates**: Group related updates when possible
503 | 


--------------------------------------------------------------------------------
/docs/useGunKeys.md:
--------------------------------------------------------------------------------
  1 | # useGunKeys
  2 | 
  3 | A hook for creating or retrieving SEA key pairs for Gun authentication with secure generation and comprehensive error handling.
  4 | 
  5 | ## Overview
  6 | 
  7 | `useGunKeys` handles the creation and management of cryptographic key pairs required for GunDB authentication. It provides secure key generation using SEA (Security, Encryption, Authorization) and supports both new key creation and existing key usage.
  8 | 
  9 | ## API Reference
 10 | 
 11 | ### Signature
 12 | 
 13 | ```typescript
 14 | useGunKeys(
 15 |   SEA: any,
 16 |   initialValue?: KeyPair | null
 17 | ): KeyPair | null
 18 | ```
 19 | 
 20 | ### Parameters
 21 | 
 22 | - `SEA` - The SEA instance for cryptographic operations
 23 | - `initialValue` - Optional existing key pair to use instead of generating new ones
 24 | 
 25 | ### Return Type
 26 | 
 27 | ```typescript
 28 | KeyPair | null; // Returns null while generating, KeyPair when ready
 29 | ```
 30 | 
 31 | ### Key Pair Interface
 32 | 
 33 | ```typescript
 34 | interface KeyPair {
 35 |   pub: string; // Public key
 36 |   priv: string; // Private key
 37 |   epub: string; // Encrypted public key
 38 |   epriv: string; // Encrypted private key
 39 | }
 40 | ```
 41 | 
 42 | ## Basic Usage
 43 | 
 44 | ### Simple Key Generation
 45 | 
 46 | ```typescript
 47 | import React from 'react';
 48 | import { useGunKeys } from '@altrx/gundb-react-hooks';
 49 | import SEA from 'gun/sea';
 50 | 
 51 | export const KeyGenerationExample: React.FC = () => {
 52 |   const keys = useGunKeys(SEA);
 53 | 
 54 |   if (!keys) {
 55 |     return (
 56 |       <div className="key-generation">
 57 |         <h3>Generating Keys...</h3>
 58 |         <p>Creating your secure cryptographic key pair</p>
 59 |         <div className="loading-spinner">⏳</div>
 60 |       </div>
 61 |     );
 62 |   }
 63 | 
 64 |   return (
 65 |     <div className="keys-ready">
 66 |       <h3>Keys Generated Successfully</h3>
 67 |       <div className="key-info">
 68 |         <p><strong>Public Key:</strong> {keys.pub.slice(0, 20)}...</p>
 69 |         <p><strong>Keys ready for authentication</strong></p>
 70 |       </div>
 71 |     </div>
 72 |   );
 73 | };
 74 | ```
 75 | 
 76 | ### Using Existing Keys
 77 | 
 78 | ```typescript
 79 | import React, { useState, useEffect } from 'react';
 80 | import { useGunKeys } from '@altrx/gundb-react-hooks';
 81 | import SEA from 'gun/sea';
 82 | 
 83 | export const ExistingKeysExample: React.FC = () => {
 84 |   const [storedKeys, setStoredKeys] = useState<KeyPair | null>(null);
 85 | 
 86 |   // Load keys from secure storage on mount
 87 |   useEffect(() => {
 88 |     const loadKeys = async () => {
 89 |       try {
 90 |         const keysData = localStorage.getItem('userKeys');
 91 |         if (keysData) {
 92 |           const parsed = JSON.parse(keysData);
 93 |           setStoredKeys(parsed);
 94 |         }
 95 |       } catch (error) {
 96 |         console.error('Failed to load stored keys:', error);
 97 |       }
 98 |     };
 99 | 
100 |     loadKeys();
101 |   }, []);
102 | 
103 |   // Use existing keys or generate new ones
104 |   const keys = useGunKeys(SEA, storedKeys);
105 | 
106 |   const handleSaveKeys = () => {
107 |     if (keys) {
108 |       try {
109 |         localStorage.setItem('userKeys', JSON.stringify(keys));
110 |         alert('Keys saved successfully!');
111 |       } catch (error) {
112 |         console.error('Failed to save keys:', error);
113 |         alert('Failed to save keys');
114 |       }
115 |     }
116 |   };
117 | 
118 |   const handleClearKeys = () => {
119 |     localStorage.removeItem('userKeys');
120 |     setStoredKeys(null);
121 |     window.location.reload();
122 |   };
123 | 
124 |   if (!keys) {
125 |     return (
126 |       <div>
127 |         <h3>⏳ {storedKeys ? 'Loading keys...' : 'Generating new keys...'}</h3>
128 |       </div>
129 |     );
130 |   }
131 | 
132 |   return (
133 |     <div className="key-management">
134 |       <h3>Key Management</h3>
135 | 
136 |       <div className="key-details">
137 |         <h4>Key Information</h4>
138 |         <p><strong>Public Key:</strong> {keys.pub}</p>
139 |         <p><strong>Encrypted Public Key:</strong> {keys.epub}</p>
140 |         <p><small>Private keys are securely stored and not displayed</small></p>
141 |       </div>
142 | 
143 |       <div className="key-actions">
144 |         {!storedKeys && (
145 |           <button onClick={handleSaveKeys} className="save-keys">
146 |             Save Keys for Later Use
147 |           </button>
148 |         )}
149 | 
150 |         {storedKeys && (
151 |           <button onClick={handleClearKeys} className="clear-keys">
152 |             Generate New Keys
153 |           </button>
154 |         )}
155 |       </div>
156 | 
157 |       <div className="security-notice">
158 |         <h4>Security Notice</h4>
159 |         <p>Keys are stored locally. In production:</p>
160 |         <ul>
161 |           <li>Use encrypted storage</li>
162 |           <li>Consider hardware security modules</li>
163 |           <li>Implement secure backup mechanisms</li>
164 |         </ul>
165 |       </div>
166 |     </div>
167 |   );
168 | };
169 | ```
170 | 
171 | ## Advanced Usage
172 | 
173 | ### Key Generation with Progress Tracking
174 | 
175 | ```typescript
176 | import React, { useState, useEffect } from 'react';
177 | import { useGunKeys } from '@altrx/gundb-react-hooks';
178 | import SEA from 'gun/sea';
179 | 
180 | export const KeyGenerationProgress: React.FC = () => {
181 |   const [startTime, setStartTime] = useState<number>(0);
182 |   const [elapsed, setElapsed] = useState<number>(0);
183 | 
184 |   const keys = useGunKeys(SEA);
185 | 
186 |   useEffect(() => {
187 |     if (!keys) {
188 |       setStartTime(Date.now());
189 |       const interval = setInterval(() => {
190 |         setElapsed(Date.now() - startTime);
191 |       }, 100);
192 | 
193 |       return () => clearInterval(interval);
194 |     }
195 |   }, [keys, startTime]);
196 | 
197 |   if (!keys) {
198 |     return (
199 |       <div className="key-progress">
200 |         <h3>Generating Cryptographic Keys</h3>
201 |         <div className="progress-info">
202 |           <p>Time elapsed: {(elapsed / 1000).toFixed(1)}s</p>
203 |           <p>Creating secure key pair...</p>
204 |           <div className="progress-bar">
205 |             <div className="progress-fill" style={{
206 |               width: `${Math.min((elapsed / 3000) * 100, 95)}%`
207 |             }} />
208 |           </div>
209 |         </div>
210 |         <div className="security-info">
211 |           <h4>What's happening?</h4>
212 |           <ul>
213 |             <li>Generating cryptographically secure random numbers</li>
214 |             <li>Creating public/private key pair</li>
215 |             <li>Encrypting keys for secure storage</li>
216 |           </ul>
217 |         </div>
218 |       </div>
219 |     );
220 |   }
221 | 
222 |   return (
223 |     <div className="keys-complete">
224 |       <h3>Keys Generated Successfully!</h3>
225 |       <p>Generation completed in {(elapsed / 1000).toFixed(1)} seconds</p>
226 |       <div className="key-summary">
227 |         <p><strong>Public Key:</strong> {keys.pub.slice(0, 40)}...</p>
228 |         <p><strong>Ready for authentication and encryption</strong></p>
229 |       </div>
230 |     </div>
231 |   );
232 | };
233 | ```
234 | 
235 | ### Key Import/Export Functionality
236 | 
237 | ```typescript
238 | import React, { useState } from 'react';
239 | import { useGunKeys } from '@altrx/gundb-react-hooks';
240 | import SEA from 'gun/sea';
241 | 
242 | export const KeyImportExport: React.FC = () => {
243 |   const [importKeys, setImportKeys] = useState<KeyPair | null>(null);
244 |   const [importText, setImportText] = useState<string>('');
245 |   const [exportFormat, setExportFormat] = useState<'json' | 'base64'>('json');
246 | 
247 |   const keys = useGunKeys(SEA, importKeys);
248 | 
249 |   const handleImport = () => {
250 |     try {
251 |       let parsed: KeyPair;
252 | 
253 |       if (importText.startsWith('{')) {
254 |         // JSON format
255 |         parsed = JSON.parse(importText);
256 |       } else {
257 |         // Base64 format
258 |         const decoded = atob(importText);
259 |         parsed = JSON.parse(decoded);
260 |       }
261 | 
262 |       // Validate key structure
263 |       if (!parsed.pub || !parsed.priv || !parsed.epub || !parsed.epriv) {
264 |         throw new Error('Invalid key format');
265 |       }
266 | 
267 |       setImportKeys(parsed);
268 |       setImportText('');
269 |     } catch (error) {
270 |       alert('Invalid key format. Please check your input.');
271 |     }
272 |   };
273 | 
274 |   const handleExport = () => {
275 |     if (!keys) return;
276 | 
277 |     try {
278 |       let exported: string;
279 | 
280 |       if (exportFormat === 'json') {
281 |         exported = JSON.stringify(keys, null, 2);
282 |       } else {
283 |         exported = btoa(JSON.stringify(keys));
284 |       }
285 | 
286 |       navigator.clipboard.writeText(exported);
287 |       alert(`Keys exported to clipboard in ${exportFormat} format!`);
288 |     } catch (error) {
289 |       console.error('Export failed:', error);
290 |       alert('Failed to export keys');
291 |     }
292 |   };
293 | 
294 |   const handleReset = () => {
295 |     setImportKeys(null);
296 |     setImportText('');
297 |     window.location.reload();
298 |   };
299 | 
300 |   if (!keys) {
301 |     return (
302 |       <div className="key-loading">
303 |         <h3>{importKeys ? 'Loading imported keys...' : 'Generating new keys...'}</h3>
304 |       </div>
305 |     );
306 |   }
307 | 
308 |   return (
309 |     <div className="key-import-export">
310 |       <h3>Key Management</h3>
311 | 
312 |       <div className="current-keys">
313 |         <h4>Current Keys</h4>
314 |         <p><strong>Public Key:</strong> {keys.pub.slice(0, 20)}...</p>
315 |         <p><strong>Status:</strong> {importKeys ? 'Imported' : 'Generated'}</p>
316 |       </div>
317 | 
318 |       <div className="export-section">
319 |         <h4>Export Keys</h4>
320 |         <div className="export-options">
321 |           <label>
322 |             <input
323 |               type="radio"
324 |               value="json"
325 |               checked={exportFormat === 'json'}
326 |               onChange={(e) => setExportFormat(e.target.value as 'json')}
327 |             />
328 |             JSON Format (Human Readable)
329 |           </label>
330 |           <label>
331 |             <input
332 |               type="radio"
333 |               value="base64"
334 |               checked={exportFormat === 'base64'}
335 |               onChange={(e) => setExportFormat(e.target.value as 'base64')}
336 |             />
337 |             Base64 Format (Compact)
338 |           </label>
339 |         </div>
340 |         <button onClick={handleExport}>
341 |           Copy Keys to Clipboard
342 |         </button>
343 |       </div>
344 | 
345 |       <div className="import-section">
346 |         <h4>Import Keys</h4>
347 |         <textarea
348 |           placeholder="Paste your keys here (JSON or Base64 format)"
349 |           value={importText}
350 |           onChange={(e) => setImportText(e.target.value)}
351 |           rows={6}
352 |           style={{ width: '100%', fontFamily: 'monospace' }}
353 |         />
354 |         <div className="import-actions">
355 |           <button onClick={handleImport} disabled={!importText.trim()}>
356 |             Import Keys
357 |           </button>
358 |           <button onClick={handleReset}>
359 |             Generate New Keys
360 |           </button>
361 |         </div>
362 |       </div>
363 | 
364 |       <div className="security-warning">
365 |         <h4>Security Guidelines</h4>
366 |         <ul>
367 |           <li><strong>Never share private keys</strong> - Only share public keys</li>
368 |           <li><strong>Store keys securely</strong> - Use encrypted storage in production</li>
369 |           <li><strong>Backup safely</strong> - Keep secure offline copies</li>
370 |           <li><strong>Verify integrity</strong> - Ensure keys haven't been tampered with</li>
371 |         </ul>
372 |       </div>
373 |     </div>
374 |   );
375 | };
376 | ```
377 | 
378 | ## Error Handling
379 | 
380 | ### Comprehensive Error Management
381 | 
382 | ```typescript
383 | function KeyGenerationWithErrorHandling() {
384 |   const [error, setError] = useState<string | null>(null);
385 |   const [isGenerating, setIsGenerating] = useState(false);
386 | 
387 |   const keys = useGunKeys(SEA);
388 | 
389 |   useEffect(() => {
390 |     if (!keys) {
391 |       setIsGenerating(true);
392 |       setError(null);
393 |     } else {
394 |       setIsGenerating(false);
395 |     }
396 |   }, [keys]);
397 | 
398 |   if (error) {
399 |     return (
400 |       <div className="key-error">
401 |         <h3>Key Generation Failed</h3>
402 |         <p>{error}</p>
403 |         <button onClick={() => window.location.reload()}>
404 |           Try Again
405 |         </button>
406 |       </div>
407 |     );
408 |   }
409 | 
410 |   if (isGenerating) {
411 |     return (
412 |       <div className="key-generating">
413 |         <h3>Generating Secure Keys</h3>
414 |         <p>This may take a few seconds...</p>
415 |       </div>
416 |     );
417 |   }
418 | 
419 |   return (
420 |     <div className="keys-ready">
421 |       <h3>Keys Ready</h3>
422 |       <p>Your cryptographic keys have been generated successfully.</p>
423 |     </div>
424 |   );
425 | }
426 | ```
427 | 
428 | ## Migration from v0.9.x
429 | 
430 | ### With Authentication Flow
431 | 
432 | ```typescript
433 | import React, { useState, useEffect } from 'react';
434 | import { useGunKeys, useGunKeyAuth, useGun } from '@altrx/gundb-react-hooks';
435 | import Gun from 'gun';
436 | import SEA from 'gun/sea';
437 | 
438 | export const CompleteAuthFlow: React.FC = () => {
439 |   const [authStep, setAuthStep] = useState<'keys' | 'auth' | 'ready'>('keys');
440 | 
441 |   const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
442 |   const keys = useGunKeys(SEA);
443 |   const [user, isLoggedIn, authError] = useGunKeyAuth(gun, keys!, false);
444 | 
445 |   // Progress through authentication steps
446 |   useEffect(() => {
447 |     if (keys && authStep === 'keys') {
448 |       setAuthStep('auth');
449 |     }
450 |   }, [keys, authStep]);
451 | 
452 |   useEffect(() => {
453 |     if (isLoggedIn && authStep === 'auth') {
454 |       setAuthStep('ready');
455 |     }
456 |   }, [isLoggedIn, authStep]);
457 | 
458 |   const startAuth = () => {
459 |     if (keys) {
460 |       // Trigger authentication
461 |       setAuthStep('auth');
462 |     }
463 |   };
464 | 
465 |   switch (authStep) {
466 |     case 'keys':
467 |       return (
468 |         <div className="step-keys">
469 |           <h3>Step 1: Key Generation</h3>
470 |           {!keys ? (
471 |             <div>
472 |               <p>Generating your cryptographic keys...</p>
473 |               <div className="spinner">⏳</div>
474 |             </div>
475 |           ) : (
476 |             <div>
477 |               <p>Keys generated successfully!</p>
478 |               <p><strong>Public Key:</strong> {keys.pub.slice(0, 30)}...</p>
479 |               <button onClick={() => setAuthStep('auth')}>
480 |                 Continue to Authentication →
481 |               </button>
482 |             </div>
483 |           )}
484 |         </div>
485 |       );
486 | 
487 |     case 'auth':
488 |       return (
489 |         <div className="step-auth">
490 |           <h3>Step 2: Authentication</h3>
491 |           {authError ? (
492 |             <div className="auth-error">
493 |               <p>Authentication failed: {authError.err}</p>
494 |               <button onClick={() => setAuthStep('keys')}>
495 |                 ← Back to Keys
496 |               </button>
497 |               <button onClick={startAuth}>
498 |                 Retry Authentication
499 |               </button>
500 |             </div>
501 |           ) : !isLoggedIn ? (
502 |             <div>
503 |               <p>Ready to authenticate with your keys</p>
504 |               <button onClick={startAuth}>
505 |                 Authenticate Now
506 |               </button>
507 |               <button onClick={() => setAuthStep('keys')}>
508 |                 ← Back to Keys
509 |               </button>
510 |             </div>
511 |           ) : (
512 |             <div>
513 |               <p>Authentication successful!</p>
514 |               <button onClick={() => setAuthStep('ready')}>
515 |                 Continue to App →
516 |               </button>
517 |             </div>
518 |           )}
519 |         </div>
520 |       );
521 | 
522 |     case 'ready':
523 |       return (
524 |         <div className="step-ready">
525 |           <h3>Step 3: Ready to Use</h3>
526 |           <p>You're now authenticated and ready to use the app!</p>
527 |           <div className="user-info">
528 |             <p><strong>Public Key:</strong> {keys!.pub}</p>
529 |             <p><strong>Authenticated:</strong> Yes</p>
530 |           </div>
531 |           <button onClick={() => {
532 |             user.leave();
533 |             setAuthStep('keys');
534 |             window.location.reload();
535 |           }}>
536 |             Logout
537 |           </button>
538 |         </div>
539 |       );
540 | 
541 |     default:
542 |       return null;
543 |   }
544 | };
545 | ```
546 | 
547 | ## Migration from v0.9.x
548 | 
549 | ### Before (v0.9.x)
550 | 
551 | ```typescript
552 | // Simple key generation without detailed state management
553 | const keys = useGunKeys(SEA);
554 | 
555 | // Limited error handling or progress indication
556 | if (!keys) {
557 |   return <div>Loading...</div>;
558 | }
559 | ```
560 | 
561 | ### After (v1.0.0)
562 | 
563 | ```typescript
564 | // Enhanced key generation with proper state management
565 | const keys = useGunKeys(SEA, existingKeys);
566 | 
567 | // Better UX with detailed loading and error states
568 | if (!keys) {
569 |   return (
570 |     <div className="key-generation">
571 |       <h3>Generating Keys...</h3>
572 |       <p>Creating your secure cryptographic key pair</p>
573 |       <ProgressIndicator />
574 |     </div>
575 |   );
576 | }
577 | 
578 | // Full key management with import/export capabilities
579 | return <KeyManagementInterface keys={keys} />;
580 | ```
581 | 
582 | ## Best Practices
583 | 
584 | 1. **Secure Storage** - Never store private keys in plain text
585 | 2. **Progress Indication** - Show users that key generation is in progress
586 | 3. **Key Validation** - Always validate imported keys before use
587 | 4. **Backup Strategy** - Implement secure key backup mechanisms
588 | 5. **Error Handling** - Handle key generation failures gracefully
589 | 6. **Performance** - Key generation can be CPU intensive, provide feedback
590 | 7. **Security Awareness** - Educate users about key security
591 | 8. **Initial Values** - Use initial values to restore existing keys efficiently
592 | 
593 | ## Security Considerations
594 | 
595 | - **Key Generation**: Uses cryptographically secure random number generation
596 | - **Storage**: Private keys should be encrypted when stored
597 | - **Transport**: Never transmit private keys over unsecured channels
598 | - **Lifecycle**: Implement proper key rotation and expiration policies
599 | - **Backup**: Secure backup mechanisms are essential for key recovery
600 | - **Validation**: Always validate key integrity and format
601 | 


--------------------------------------------------------------------------------
/docs/useGun.md:
--------------------------------------------------------------------------------
  1 | # useGun
  2 | 
  3 | A hook for initializing and managing a GunDB instance with enhanced connection monitoring and error handling.
  4 | 
  5 | ## API Reference
  6 | 
  7 | ### Signature
  8 | 
  9 | ```typescript
 10 | useGun(
 11 |   Gun: any, 
 12 |   options?: GunOptions
 13 | ): IGunInstance
 14 | ```
 15 | 
 16 | ### Parameters
 17 | 
 18 | - `Gun` - The Gun constructor
 19 | - `options` - Gun configuration options (peers, localStorage, etc.)
 20 | 
 21 | ### Return Type
 22 | 
 23 | ```typescript
 24 | IGunInstance  // Configured Gun instance with connection monitoring
 25 | ```
 26 | 
 27 | ### Gun Options Interface
 28 | 
 29 | ```typescript
 30 | interface GunOptions {
 31 |   peers?: string[];        // Array of peer URLs
 32 |   localStorage?: boolean;  // Enable localStorage persistence
 33 |   sessionStorage?: boolean; // Enable sessionStorage persistence
 34 |   radisk?: boolean;       // Enable radisk storage
 35 |   file?: string;          // File path for server-side storage
 36 |   web?: any;              // Web server instance
 37 |   [key: string]: any;     // Additional Gun options
 38 | }
 39 | ```
 40 | 
 41 | ## Basic Usage
 42 | 
 43 | ### Simple Gun Instance
 44 | 
 45 | ```typescript
 46 | import React from 'react';
 47 | import { useGun, useGunConnection } from '@altrx/gundb-react-hooks';
 48 | import Gun from 'gun';
 49 | 
 50 | export const BasicGunApp: React.FC = () => {
 51 |   // Initialize Gun with basic peer configuration
 52 |   const gun = useGun(Gun, { 
 53 |     peers: ['http://localhost:8765/gun'] 
 54 |   });
 55 |   
 56 |   const { isConnected, connectionError } = useGunConnection(gun);
 57 | 
 58 |   if (connectionError) {
 59 |     return (
 60 |       <div className="connection-error">
 61 |         <h3>Connection Error</h3>
 62 |         <p>{connectionError.err}</p>
 63 |         <button onClick={() => window.location.reload()}>
 64 |           Retry Connection
 65 |         </button>
 66 |       </div>
 67 |     );
 68 |   }
 69 | 
 70 |   return (
 71 |     <div className="gun-app">
 72 |       <h3>Gun Database Connected</h3>
 73 |       
 74 |       <div className="connection-status">
 75 |         <p><strong>Status:</strong> {isConnected ? 'Connected' : 'Disconnected'}</p>
 76 |         <p><strong>Gun Instance:</strong> {gun ? 'Ready' : 'Not Ready'}</p>
 77 |       </div>
 78 | 
 79 |       {gun && <MainApp gun={gun} />}
 80 |     </div>
 81 |   );
 82 | };
 83 | 
 84 | const MainApp: React.FC<{ gun: any }> = ({ gun }) => {
 85 |   return (
 86 |     <div>
 87 |       <h4>Main Application</h4>
 88 |       <p>Gun instance is ready for use!</p>
 89 |     </div>
 90 |   );
 91 | };
 92 | ```
 93 | 
 94 | ### Multiple Peer Configuration
 95 | 
 96 | ```typescript
 97 | import React from 'react';
 98 | import { useGun, useGunConnection } from '@altrx/gundb-react-hooks';
 99 | import Gun from 'gun';
100 | 
101 | export const MultiPeerGunApp: React.FC = () => {
102 |   // Configure multiple peers for redundancy
103 |   const gun = useGun(Gun, {
104 |     peers: [
105 |       'http://localhost:8765/gun',
106 |       'https://gun-manhattan.herokuapp.com/gun',
107 |       'https://peer1.example.com/gun',
108 |       'https://peer2.example.com/gun'
109 |     ],
110 |     localStorage: true,  // Enable local persistence
111 |     radisk: true        // Enable radisk for better performance
112 |   });
113 | 
114 |   const { isConnected, peerCount, connectionError } = useGunConnection(gun);
115 | 
116 |   if (connectionError) {
117 |     return (
118 |       <div className="multi-peer-error">
119 |         <h3>Multi-Peer Connection Error</h3>
120 |         <p><strong>Error:</strong> {connectionError.err}</p>
121 |         <p>Trying to connect to multiple peers...</p>
122 |         
123 |         <div className="retry-options">
124 |           <button onClick={() => window.location.reload()}>
125 |             Retry All Peers
126 |           </button>
127 |         </div>
128 |       </div>
129 |     );
130 |   }
131 | 
132 |   return (
133 |     <div className="multi-peer-app">
134 |       <h3>Multi-Peer Gun Database</h3>
135 |       
136 |       <div className="connection-details">
137 |         <div className="status-card">
138 |           <h4>Connection Status</h4>
139 |           <p><strong>Status:</strong> {isConnected ? 'Connected' : 'Disconnected'}</p>
140 |           <p><strong>Connected Peers:</strong> {peerCount || 0}</p>
141 |           <p><strong>Local Storage:</strong> Enabled</p>
142 |           <p><strong>Radisk:</strong> Enabled</p>
143 |         </div>
144 |         
145 |         <div className="peer-list">
146 |           <h4>Configured Peers:</h4>
147 |           <ul>
148 |             <li>localhost:8765 (Local)</li>
149 |             <li>gun-manhattan.herokuapp.com (Public)</li>
150 |             <li>peer1.example.com (Custom)</li>
151 |             <li>peer2.example.com (Custom)</li>
152 |           </ul>
153 |         </div>
154 |       </div>
155 | 
156 |       {gun && <PeerMonitoringApp gun={gun} />}
157 |     </div>
158 |   );
159 | };
160 | 
161 | const PeerMonitoringApp: React.FC<{ gun: any }> = ({ gun }) => {
162 |   const [peerStats, setPeerStats] = React.useState<any[]>([]);
163 | 
164 |   React.useEffect(() => {
165 |     // Monitor peer connections
166 |     if (gun && gun.on) {
167 |       gun.on('hi', (peer: any) => {
168 |         console.log('Peer connected:', peer);
169 |         setPeerStats(prev => [...prev, { peer, connectedAt: new Date() }]);
170 |       });
171 |       
172 |       gun.on('bye', (peer: any) => {
173 |         console.log('Peer disconnected:', peer);
174 |         setPeerStats(prev => prev.filter(p => p.peer !== peer));
175 |       });
176 |     }
177 |   }, [gun]);
178 | 
179 |   return (
180 |     <div className="peer-monitoring">
181 |       <h4>Peer Monitoring</h4>
182 |       <p>Active Connections: {peerStats.length}</p>
183 |       
184 |       {peerStats.map((stat, index) => (
185 |         <div key={index} className="peer-stat">
186 |           <p>Peer {index + 1} - Connected at {stat.connectedAt.toLocaleTimeString()}</p>
187 |         </div>
188 |       ))}
189 |     </div>
190 |   );
191 | };
192 | ```
193 | 
194 | ## Advanced Usage
195 | 
196 | ### Environment-Aware Configuration
197 | 
198 | ```typescript
199 | import React from 'react';
200 | import { useGun } from '@altrx/gundb-react-hooks';
201 | import Gun from 'gun';
202 | 
203 | const getGunConfig = (environment: string): GunOptions => {
204 |   switch (environment) {
205 |     case 'development':
206 |       return {
207 |         peers: ['http://localhost:8765/gun'],
208 |         localStorage: true,
209 |         radisk: true
210 |       };
211 |       
212 |     case 'staging':
213 |       return {
214 |         peers: [
215 |           'https://staging-gun-1.example.com/gun',
216 |           'https://staging-gun-2.example.com/gun'
217 |         ],
218 |         localStorage: true,
219 |         radisk: true
220 |       };
221 |       
222 |     case 'production':
223 |       return {
224 |         peers: [
225 |           'https://gun-1.example.com/gun',
226 |           'https://gun-2.example.com/gun',
227 |           'https://gun-3.example.com/gun',
228 |           'https://gun-manhattan.herokuapp.com/gun'
229 |         ],
230 |         localStorage: true,
231 |         radisk: true,
232 |         sessionStorage: false  // Disable in production for security
233 |       };
234 |       
235 |     default:
236 |       return {
237 |         peers: ['https://gun-manhattan.herokuapp.com/gun'],
238 |         localStorage: true
239 |       };
240 |   }
241 | };
242 | 
243 | export const EnvironmentAwareGunApp: React.FC = () => {
244 |   const environment = process.env.NODE_ENV || 'development';
245 |   const gunConfig = getGunConfig(environment);
246 |   
247 |   const gun = useGun(Gun, gunConfig);
248 |   const { isConnected, connectionError } = useGunConnection(gun);
249 | 
250 |   return (
251 |     <div className="env-aware-app">
252 |       <h3>Environment-Aware Gun App</h3>
253 |       
254 |       <div className="environment-info">
255 |         <h4>Environment: {environment.toUpperCase()}</h4>
256 |         <div className="config-display">
257 |           <h5>Gun Configuration:</h5>
258 |           <pre>{JSON.stringify(gunConfig, null, 2)}</pre>
259 |         </div>
260 |       </div>
261 | 
262 |       <div className="connection-status">
263 |         {connectionError ? (
264 |           <div className="error">
265 |             <p>Connection Error: {connectionError.err}</p>
266 |           </div>
267 |         ) : (
268 |           <div className="success">
269 |             <p>Status: {isConnected ? 'Connected' : 'Connecting...'}</p>
270 |           </div>
271 |         )}
272 |       </div>
273 | 
274 |       {gun && <EnvironmentSpecificFeatures gun={gun} environment={environment} />}
275 |     </div>
276 |   );
277 | };
278 | 
279 | const EnvironmentSpecificFeatures: React.FC<{ 
280 |   gun: any; 
281 |   environment: string; 
282 | }> = ({ gun, environment }) => {
283 |   const isDevelopment = environment === 'development';
284 |   const isProduction = environment === 'production';
285 | 
286 |   return (
287 |     <div className="env-features">
288 |       <h4>Environment Features</h4>
289 |       
290 |       {isDevelopment && (
291 |         <div className="dev-features">
292 |           <h5>Development Mode</h5>
293 |           <ul>
294 |             <li>Local Gun peer</li>
295 |             <li>Debug logging enabled</li>
296 |             <li>Hot reloading support</li>
297 |             <li>All storage options enabled</li>
298 |           </ul>
299 |         </div>
300 |       )}
301 |       
302 |       {isProduction && (
303 |         <div className="prod-features">
304 |           <h5>Production Mode</h5>
305 |           <ul>
306 |             <li>Multiple redundant peers</li>
307 |             <li>Optimized for performance</li>
308 |             <li>Enhanced security settings</li>
309 |             <li>Error reporting enabled</li>
310 |           </ul>
311 |         </div>
312 |       )}
313 |     </div>
314 |   );
315 | };
316 | ```
317 | 
318 | ### Gun with Custom Storage
319 | 
320 | ```typescript
321 | import React from 'react';
322 | import { useGun } from '@altrx/gundb-react-hooks';
323 | import Gun from 'gun';
324 | import 'gun/lib/radix';
325 | import 'gun/lib/radisk';
326 | import 'gun/lib/store';
327 | import 'gun/lib/rindexed';
328 | 
329 | export const CustomStorageGunApp: React.FC = () => {
330 |   // Configure Gun with custom storage options
331 |   const gun = useGun(Gun, {
332 |     peers: ['http://localhost:8765/gun'],
333 |     localStorage: true,     // Browser localStorage
334 |     sessionStorage: false,  // Disable session storage
335 |     radisk: true,          // Enable radisk for performance
336 |     file: 'data.json',     // Server-side file storage (if applicable)
337 |     // Custom storage adapter
338 |     store: (key: string, data: any, cb: Function) => {
339 |       // Custom storage implementation
340 |       try {
341 |         if (data === undefined) {
342 |           // Read operation
343 |           const stored = localStorage.getItem(`custom_gun_${key}`);
344 |           cb(null, stored ? JSON.parse(stored) : undefined);
345 |         } else {
346 |           // Write operation
347 |           localStorage.setItem(`custom_gun_${key}`, JSON.stringify(data));
348 |           cb(null, data);
349 |         }
350 |       } catch (error) {
351 |         cb(error);
352 |       }
353 |     }
354 |   });
355 | 
356 |   const { isConnected, connectionError } = useGunConnection(gun);
357 | 
358 |   const checkStorageUsage = () => {
359 |     try {
360 |       const gunKeys = Object.keys(localStorage).filter(key => 
361 |         key.startsWith('gun/') || key.startsWith('custom_gun_')
362 |       );
363 |       
364 |       const usage = gunKeys.reduce((total, key) => {
365 |         return total + localStorage.getItem(key)!.length;
366 |       }, 0);
367 |       
368 |       console.log(`Gun storage usage: ${(usage / 1024).toFixed(2)} KB`);
369 |       console.log(`Gun keys count: ${gunKeys.length}`);
370 |     } catch (error) {
371 |       console.error('Failed to check storage usage:', error);
372 |     }
373 |   };
374 | 
375 |   return (
376 |     <div className="custom-storage-app">
377 |       <h3>Custom Storage Gun App</h3>
378 |       
379 |       <div className="storage-config">
380 |         <h4>Storage Configuration:</h4>
381 |         <ul>
382 |           <li>LocalStorage: Enabled</li>
383 |           <li>SessionStorage: Disabled</li>
384 |           <li>Radisk: Enabled (Performance)</li>
385 |           <li>Custom Storage Adapter: Active</li>
386 |         </ul>
387 |       </div>
388 | 
389 |       <div className="storage-controls">
390 |         <button onClick={checkStorageUsage}>
391 |           Check Storage Usage
392 |         </button>
393 |         <button onClick={() => {
394 |           if (confirm('Clear all Gun storage data?')) {
395 |             Object.keys(localStorage)
396 |               .filter(key => key.startsWith('gun/') || key.startsWith('custom_gun_'))
397 |               .forEach(key => localStorage.removeItem(key));
398 |             window.location.reload();
399 |           }
400 |         }}>
401 |           Clear Storage
402 |         </button>
403 |       </div>
404 | 
405 |       {connectionError ? (
406 |         <div className="error">
407 |           <p>Connection Error: {connectionError.err}</p>
408 |         </div>
409 |       ) : (
410 |         <div className="status">
411 |           <p>Status: {isConnected ? 'Connected' : 'Connecting...'}</p>
412 |         </div>
413 |       )}
414 | 
415 |       {gun && <StorageTestApp gun={gun} />}
416 |     </div>
417 |   );
418 | };
419 | 
420 | const StorageTestApp: React.FC<{ gun: any }> = ({ gun }) => {
421 |   const [testData, setTestData] = React.useState<string>('');
422 |   const [storedValue, setStoredValue] = React.useState<string>('');
423 | 
424 |   const saveToStorage = () => {
425 |     if (!testData.trim()) return;
426 |     
427 |     gun.get('storage_test').put({
428 |       data: testData,
429 |       timestamp: new Date().toISOString()
430 |     });
431 |     
432 |     setTestData('');
433 |   };
434 | 
435 |   const loadFromStorage = () => {
436 |     gun.get('storage_test').once((data: any) => {
437 |       if (data) {
438 |         setStoredValue(`${data.data} (saved at ${data.timestamp})`);
439 |       } else {
440 |         setStoredValue('No data found');
441 |       }
442 |     });
443 |   };
444 | 
445 |   return (
446 |     <div className="storage-test">
447 |       <h4>Storage Test</h4>
448 |       
449 |       <div className="test-controls">
450 |         <input
451 |           type="text"
452 |           placeholder="Enter test data"
453 |           value={testData}
454 |           onChange={(e) => setTestData(e.target.value)}
455 |         />
456 |         <button onClick={saveToStorage}>Save</button>
457 |         <button onClick={loadFromStorage}>Load</button>
458 |       </div>
459 |       
460 |       {storedValue && (
461 |         <div className="stored-value">
462 |           <h5>Stored Value:</h5>
463 |           <p>{storedValue}</p>
464 |         </div>
465 |       )}
466 |     </div>
467 |   );
468 | };
469 | ```
470 | 
471 | ## Error Handling Patterns
472 | 
473 | ### Connection Retry Logic
474 | 
475 | ```typescript
476 | const GunWithRetry: React.FC = () => {
477 |   const [retryCount, setRetryCount] = useState(0);
478 |   const [isRetrying, setIsRetrying] = useState(false);
479 |   
480 |   const gun = useGun(Gun, { 
481 |     peers: ['http://localhost:8765/gun'] 
482 |   });
483 |   
484 |   const { isConnected, connectionError } = useGunConnection(gun);
485 | 
486 |   const handleRetry = async () => {
487 |     setIsRetrying(true);
488 |     setRetryCount(prev => prev + 1);
489 |     
490 |     // Wait before retry
491 |     await new Promise(resolve => setTimeout(resolve, 1000 * retryCount));
492 |     
493 |     // Reload the app to reinitialize Gun
494 |     window.location.reload();
495 |   };
496 | 
497 |   if (connectionError && !isRetrying) {
498 |     return (
499 |       <div className="connection-retry">
500 |         <h3>Connection Failed</h3>
501 |         <p>{connectionError.err}</p>
502 |         <p>Retry attempts: {retryCount}</p>
503 |         
504 |         <button 
505 |           onClick={handleRetry}
506 |           disabled={retryCount >= 5}
507 |         >
508 |           {retryCount >= 5 ? 'Max Retries Reached' : 'Retry Connection'}
509 |         </button>
510 |         
511 |         {retryCount >= 5 && (
512 |           <div className="fallback-options">
513 |             <h4>Alternative Options:</h4>
514 |             <button onClick={() => window.location.reload()}>
515 |               Try Different Peers
516 |             </button>
517 |             <button onClick={() => {
518 |               localStorage.clear();
519 |               window.location.reload();
520 |             }}>
521 |               Clear Cache & Retry
522 |             </button>
523 |           </div>
524 |         )}
525 |       </div>
526 |     );
527 |   }
528 | 
529 |   return (
530 |     <div>
531 |       <p>Status: {isConnected ? 'Connected' : 'Connecting...'}</p>
532 |       {gun && <div>Gun ready!</div>}
533 |     </div>
534 |   );
535 | };
536 | ```
537 | 
538 | ## Migration from v0.9.x
539 | 
540 | ### Before (v0.9.x)
541 | 
542 | ```typescript
543 | // Simple Gun initialization without connection monitoring
544 | const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
545 | 
546 | // No built-in error handling or connection status
547 | if (gun) {
548 |   // Assume Gun is ready to use
549 | }
550 | ```
551 | 
552 | ### After (v1.0.0)
553 | 
554 | ```typescript
555 | // Enhanced Gun initialization with connection monitoring
556 | const gun = useGun(Gun, { peers: ['http://localhost:8765/gun'] });
557 | const { isConnected, connectionError } = useGunConnection(gun);
558 | 
559 | // Comprehensive connection status handling
560 | if (connectionError) {
561 |   return <ConnectionErrorComponent error={connectionError} />;
562 | }
563 | 
564 | if (!isConnected) {
565 |   return <ConnectingComponent />;
566 | }
567 | 
568 | // Gun is ready and connected
569 | return <MainApp gun={gun} />;
570 | ```
571 | 
572 | ## Best Practices
573 | 
574 | 1. **Multiple Peers** - Configure multiple peers for redundancy
575 | 2. **Environment Configuration** - Use different configs for dev/staging/prod
576 | 3. **Connection Monitoring** - Always monitor connection status
577 | 4. **Error Handling** - Implement retry logic for connection failures
578 | 5. **Storage Options** - Enable appropriate storage for your use case
579 | 6. **Performance** - Use radisk for better performance
580 | 7. **Security** - Disable sessionStorage in production if not needed
581 | 8. **Monitoring** - Track peer connections and health
582 | 
583 | ## Configuration Options
584 | 
585 | ### Development
586 | 
587 | ```typescript
588 | const devConfig: GunOptions = {
589 |   peers: ['http://localhost:8765/gun'],
590 |   localStorage: true,
591 |   radisk: true,
592 |   // Enable debug logging in development
593 |   debug: true
594 | };
595 | ```
596 | 
597 | ### Production
598 | 
599 | ```typescript
600 | const prodConfig: GunOptions = {
601 |   peers: [
602 |     'https://gun-1.example.com/gun',
603 |     'https://gun-2.example.com/gun',
604 |     'https://gun-3.example.com/gun'
605 |   ],
606 |   localStorage: true,
607 |   radisk: true,
608 |   sessionStorage: false,  // Security consideration
609 |   // Production optimizations
610 |   timeout: 15000,
611 |   retry: 3
612 | };
613 | ```
614 | 


--------------------------------------------------------------------------------
/preact/dist/gundb-react-hooks.modern.js.map:
--------------------------------------------------------------------------------
1 | {"version":3,"file":"gundb-react-hooks.modern.js","sources":["../../src/index.ts"],"sourcesContent":["import React, { useState, useEffect, useReducer, useRef } from 'react';\n\nexport type GunStatic = any;\n\nexport type GunRef = any;\n\nexport type NamespacedRef = any;\n\nexport type KeyPair = {\n  pub: string;\n  priv: string;\n  epub: string;\n  epriv: string;\n};\n\nexport type Options = {\n  appKeys?: undefined | string | KeyPair;\n  sea?: any;\n  interval?: number;\n  useOpen?: boolean;\n};\n\nexport type NodeT<T> = T & { nodeID: string; [key: string]: any };\n\nexport type ActionType<T> =\n  | { type: 'add'; data: NodeT<T> }\n  | { type: 'update'; data: NodeT<T> }\n  | { type: 'remove'; data: NodeT<T> };\n\nexport type UpdateType = {\n  id: string;\n  data: any;\n};\n\nexport interface GunOptions\n  extends Partial<{\n    file: string;\n    web: any;\n    s3: {\n      key: any;\n      secret: any;\n      bucket: any;\n    };\n    peers: string[] | Record<string, {}>;\n    radisk: boolean;\n    localStorage: boolean;\n    uuid(): string;\n    [key: string]: any;\n  }> {}\n\nexport interface CollectionState<T>\n  extends Partial<{\n    collection: Map<string, T>;\n    sorted: T[];\n    infiniteScrolling: {\n      isFetching: boolean;\n      lastFetched: string;\n      reverse: boolean;\n    };\n  }> {}\n\nexport const encryptData = async (\n  data: any,\n  keys: undefined | string | KeyPair,\n  sea: any\n) => {\n  return keys && sea ? sea.encrypt(data, keys) : Promise.resolve(data);\n};\n\nexport const decryptData = async (\n  data: any,\n  keys: undefined | string | KeyPair,\n  sea: any\n) => {\n  return keys && sea ? sea.decrypt(data, keys) : Promise.resolve(data);\n};\n\nexport const debouncedUpdates = (\n  dispatcher: any,\n  type = 'object',\n  timeout = 100\n) => {\n  let updates: any[] = [];\n  let handler: any;\n  return (update: UpdateType) => {\n    updates.push(update);\n    if (!handler) {\n      handler = setTimeout(() => {\n        let newStateSlice = updates.reduce(\n          (previousState, { id, data }) => {\n            if (type === 'object') {\n              previousState[id] = data;\n            } else {\n              previousState.set(id, data);\n            }\n            return previousState;\n          },\n          type === 'object' ? {} : new Map()\n        );\n        dispatcher(newStateSlice);\n        updates = [];\n        handler = null;\n      }, timeout);\n    }\n\n    return () => {\n      clearTimeout(handler);\n      updates = [];\n      handler = null;\n    };\n  };\n};\n\nexport const useIsMounted = () => {\n  const isMounted = useRef(false);\n  useEffect(() => {\n    isMounted.current = true;\n    return () => {\n      isMounted.current = false;\n    };\n  }, []);\n  return isMounted;\n};\n\nexport const nodeReducer = <T>(\n  state: NodeT<T>,\n  { data, type }: ActionType<T>\n): T => {\n  switch (type) {\n    case 'add':\n      return { ...state, ...data };\n    case 'remove':\n      delete state[data.nodeID];\n      return { ...state };\n    default:\n      throw new Error();\n  }\n};\n\nexport const collectionReducer = <T>(\n  state: CollectionState<T>,\n  { data, type }: ActionType<T>\n): CollectionState<T> => {\n  switch (type) {\n    case 'add':\n      data.forEach((data: NodeT<T>) => {\n        state.collection?.set(data.nodeID, data);\n      });\n      return {\n        ...state,\n        collection: state.collection,\n      };\n    case 'update':\n      state.collection?.set(data.nodeID, data);\n      return {\n        ...state,\n        collection: state.collection,\n      };\n    case 'remove':\n      state.collection?.delete(data.nodeID);\n      return {\n        ...state,\n        collection: state.collection,\n      };\n    default:\n      throw new Error();\n  }\n};\n\nexport const useSafeReducer = <T>(\n  reducer: any,\n  initialState: T\n): [T, Function] => {\n  const [state, dispatch] = useReducer<React.Reducer<T, ActionType<T>>>(\n    reducer,\n    initialState\n  );\n  const isMounted = useIsMounted();\n\n  function safeDispatch(args: ActionType<T>) {\n    if (isMounted.current) {\n      dispatch(args);\n    }\n  }\n\n  return [state, safeDispatch];\n};\n\nexport const useGun = (Gun: GunStatic, opts: GunOptions) => {\n  const [gun, setGun] = useState(Gun({ ...opts }));\n\n  useEffect(() => {\n    if (opts) {\n      setGun(Gun({ ...opts }));\n    }\n  }, [Gun, opts]);\n\n  return gun;\n};\n\nexport const useGunNamespace = (gun: GunRef, soul?: string) => {\n  const [namespace, setNamespace] = useState(\n    soul ? gun.user(soul) : gun.user()\n  );\n  useEffect(() => {\n    if (gun && !namespace) {\n      setNamespace(soul ? gun.user(soul) : gun.user());\n    }\n  }, [namespace, gun, soul]);\n  return namespace;\n};\n\nexport const useGunKeyAuth = (\n  gun: GunRef,\n  keys: KeyPair,\n  triggerAuth: boolean = true\n) => {\n  // Will attempt to perform a login (when triggerAuth is set to true),\n  // or, if false, returns a namespaced gun node\n  const namespacedGraph = useGunNamespace(gun);\n  const [isLoggedIn, setIsLoggedIn] = useState(false);\n\n  gun.on('auth', () => {\n    setIsLoggedIn(true);\n  });\n\n  useEffect(() => {\n    if (namespacedGraph && !namespacedGraph.is && keys && triggerAuth) {\n      namespacedGraph.auth(keys);\n    }\n  }, [triggerAuth, namespacedGraph, keys]);\n\n  return [namespacedGraph, isLoggedIn];\n};\n\nexport const useGunKeys = (\n  sea: any,\n  existingKeys?: KeyPair | undefined | null\n) => {\n  const [newKeys, setNewKeys] = useState<KeyPair | undefined | null>(\n    existingKeys\n  );\n\n  useEffect(() => {\n    async function getKeySet() {\n      const pair: KeyPair = await sea.pair();\n      setNewKeys(pair);\n    }\n\n    if (!newKeys && !existingKeys) {\n      getKeySet();\n    }\n\n    if (existingKeys) {\n      setNewKeys(existingKeys);\n    }\n  }, [existingKeys, newKeys, sea]);\n\n  return newKeys;\n};\n\nexport const useGunOnNodeUpdated = <T>(\n  ref: GunRef,\n  opts: Options = {\n    appKeys: '',\n    sea: null,\n    useOpen: false,\n  },\n  cb: (data: T, nodeID: string) => void,\n  cleanup?: () => void\n) => {\n  const { appKeys, sea, useOpen } = opts;\n  const handler = useRef(null);\n  const isMounted = useIsMounted();\n\n  useEffect(() => {\n    if (isMounted.current) {\n      const gunCb = async (\n        encryptedField: any,\n        nodeID: string,\n        message: any,\n        event: any\n      ) => {\n        let decryptedField = await decryptData(encryptedField, appKeys, sea);\n        cb(decryptedField, nodeID);\n\n        if (!handler.current) {\n          handler.current = event;\n        }\n      };\n\n      if (useOpen) {\n        if (!ref.open) {\n          throw new Error('Please include gun/lib/open.');\n        } else {\n          ref.open(gunCb);\n        }\n      } else {\n        ref.on(gunCb);\n      }\n    }\n\n    return () => {\n      if (handler.current) {\n        //cleanup gun .on listener\n        handler.current.off();\n      }\n      if (cleanup) {\n        cleanup();\n      }\n    };\n  }, [ref]);\n};\n\nexport const useGunState = <T>(\n  ref: GunRef,\n  opts: Options = {\n    appKeys: '',\n    sea: null,\n    interval: 100,\n    useOpen: false,\n  }\n) => {\n  const { appKeys, sea, interval = 100 } = opts;\n  const [fields, dispatch] = useSafeReducer<T>(nodeReducer, {} as T);\n\n  const debouncedHandlers: Function[] = [];\n  const updater = debouncedUpdates(\n    (data: any) => {\n      dispatch({ type: 'add', data });\n    },\n    'object',\n    interval\n  );\n\n  useGunOnNodeUpdated(\n    ref,\n    opts,\n    (item: any) => {\n      Object.keys(item).forEach((key) => {\n        let cleanFn = updater({ id: key, data: item[key] });\n        debouncedHandlers.push(cleanFn);\n      });\n    },\n    () => {\n      if (debouncedHandlers.length) {\n        //cleanup timeouts\n        debouncedHandlers.forEach((c) => c());\n      }\n    }\n  );\n\n  // Working with root node fields\n  const put = async (data: T) => {\n    let encryptedData = await encryptData(data, appKeys, sea);\n    await new Promise((resolve, reject) =>\n      ref.put(encryptedData, (ack: any) =>\n        ack.err ? reject(ack.err) : resolve(data)\n      )\n    );\n  };\n\n  const remove = async (field: string) => {\n    await new Promise((resolve, reject) =>\n      ref.put(null, (ack: any) => (ack.err ? reject(ack.err) : resolve(field)))\n    );\n    dispatch({ type: 'remove', data: { nodeID: field } });\n  };\n\n  return { fields, put, remove };\n};\n\nexport const useGunCollectionState = <T>(\n  ref: GunRef,\n  opts: Options = {\n    appKeys: '',\n    sea: null,\n    interval: 100,\n    useOpen: false,\n  }\n) => {\n  const { appKeys, sea, interval = 100 } = opts;\n  const [{ collection }, dispatch] = useSafeReducer<CollectionState<T>>(\n    collectionReducer,\n    {\n      collection: new Map(),\n    }\n  );\n\n  const debouncedHandlers: Function[] = [];\n  const updater = debouncedUpdates(\n    (data: T) => {\n      dispatch({ type: 'add', data });\n    },\n    'map',\n    interval\n  );\n\n  useGunOnNodeUpdated(\n    ref.map(),\n    opts,\n    (item: T, nodeID) => {\n      if (item) {\n        let cleanFn = updater({\n          id: nodeID,\n          data: { ...item, nodeID },\n        });\n        debouncedHandlers.push(cleanFn);\n      }\n    },\n    () => {\n      if (debouncedHandlers.length) {\n        //cleanup timeouts\n        debouncedHandlers.forEach((c) => c());\n      }\n    }\n  );\n\n  // Working with Sets\n\n  const updateInSet = async (nodeID: string, data: T) => {\n    let encryptedData = await encryptData(data, appKeys, sea);\n    await new Promise((resolve, reject) =>\n      ref\n        .get(nodeID)\n        .put(encryptedData, (ack: any) =>\n          ack.err ? reject(ack.err) : resolve(data)\n        )\n    );\n    dispatch({ type: 'update', data: { nodeID, ...data } });\n  };\n\n  const addToSet = async (data: T, nodeID?: string) => {\n    let encryptedData = await encryptData(data, appKeys, sea);\n    if (!nodeID) {\n      await new Promise((resolve, reject) =>\n        ref.set(encryptedData, (ack: any) =>\n          ack.err ? reject(ack.err) : resolve(data)\n        )\n      );\n    } else {\n      await new Promise((resolve, reject) =>\n        ref\n          .get(nodeID)\n          .put(encryptedData, (ack: any) =>\n            ack.err ? reject(ack.err) : resolve(data)\n          )\n      );\n    }\n  };\n\n  const removeFromSet = async (nodeID: string) => {\n    await new Promise((resolve, reject) =>\n      ref\n        .get(nodeID)\n        .put(null, (ack: any) => (ack.err ? reject(ack.err) : resolve(nodeID)))\n    );\n  };\n\n  return { collection, addToSet, updateInSet, removeFromSet };\n};\n"],"names":["encryptData","data","keys","sea","encrypt","Promise","resolve","decryptData","decrypt","debouncedUpdates","dispatcher","type","timeout","updates","handler","update","push","setTimeout","newStateSlice","reduce","previousState","id","set","Map","clearTimeout","useIsMounted","isMounted","useRef","useEffect","current","nodeReducer","state","nodeID","Error","collectionReducer","forEach","collection","delete","useSafeReducer","reducer","initialState","dispatch","useReducer","safeDispatch","args","useGun","Gun","opts","gun","setGun","useState","useGunNamespace","soul","namespace","setNamespace","user","useGunKeyAuth","triggerAuth","namespacedGraph","isLoggedIn","setIsLoggedIn","on","is","auth","useGunKeys","existingKeys","newKeys","setNewKeys","getKeySet","pair","useGunOnNodeUpdated","ref","appKeys","useOpen","cb","cleanup","gunCb","encryptedField","message","event","decryptedField","open","off","useGunState","interval","fields","debouncedHandlers","updater","item","Object","key","cleanFn","length","c","put","encryptedData","reject","ack","err","remove","field","useGunCollectionState","map","updateInSet","get","addToSet","removeFromSet"],"mappings":"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"}


--------------------------------------------------------------------------------