shogun-core 3.0.8 → 3.0.9

package/README.md

@@ -21,6 +21,7 @@ Shogun Core is a comprehensive SDK for building decentralized applications (dApp
 - ✅ **Type Consistency**: Unified return types across all authentication methods
 - 🚀 **Simplified Architecture**: Focused on core functionality with reduced complexity
 - ⭐ **Simple API**: Easy-to-use wrapper for common operations with minimal complexity
+- 🔗 **Advanced Chaining**: Powerful chaining operations for complex nested data structures
 - 👤 **User Space Management**: Complete CRUD operations for user-specific data storage
 - ⚡ **Quick Start**: Rapid initialization with pre-configured setups
 - 🎛️ **Configuration Presets**: Pre-built configurations for common use cases
@@ -30,6 +31,7 @@ Shogun Core is a comprehensive SDK for building decentralized applications (dApp
 ### ✅ **Major API Improvements & Simplification**
 
 - **⭐ NEW: Simple API Layer**: Added `SimpleGunAPI` with simplified methods for common operations
+- **⭐ NEW: Advanced Chaining**: Added `node()`, `chain()`, and `getNode()` methods for powerful data chaining
 - **⭐ NEW: User Space Management**: Complete CRUD operations for user-specific data storage
 - **⭐ NEW: Quick Start Functions**: `quickStart()` and `QuickStart` class for rapid initialization
 - **⭐ NEW: Improved Type System**: Reduced `any` usage with better TypeScript types
@@ -181,6 +183,19 @@ const data = await shogun.api.get('path/to/data');
 await shogun.api.set('path/to/data', { value: 'updated' });
 await shogun.api.remove('path/to/data');
 
+// Advanced chaining operations (NEW!)
+// Direct Gun node chaining - recommended for complex operations
+await shogun.api.node('users').get('alice').get('profile').put({ name: 'Alice' });
+const profile = await shogun.api.node('users').get('alice').get('profile').once();
+
+// Simplified chaining wrapper
+await shogun.api.chain('users').get('alice').get('settings').put({ theme: 'dark' });
+const settings = await shogun.api.chain('users').get('alice').get('settings').once();
+
+// Get Gun node for advanced operations like .map()
+const userNode = shogun.api.getNode('users');
+userNode.map((user, userId) => console.log(`User ${userId}:`, user));
+
 // User space operations (requires login)
 await shogun.api.putUserData('preferences', { theme: 'dark' });
 const prefs = await shogun.api.getUserData('preferences');
@@ -221,6 +236,140 @@ const userExists = await shogun.api.userExists('username');
 const user = await shogun.api.getUser('username');
 ```
 
+## 🔗 **NEW: Advanced Chaining Operations**
+
+Shogun Core now supports powerful chaining operations for complex data structures. You have three options depending on your needs:
+
+### 1. **Direct Gun Node Chaining (Recommended)**
+
+Use `node()` for full Gun.js functionality with chaining:
+
+```typescript
+// Store nested data
+await shogun.api.node('users').get('alice').get('profile').put({
+  name: 'Alice Smith',
+  email: 'alice@example.com',
+  preferences: {
+    theme: 'dark',
+    language: 'en'
+  }
+});
+
+// Read nested data
+const profile = await shogun.api.node('users').get('alice').get('profile').once();
+
+// Update specific fields
+await shogun.api.node('users').get('alice').get('profile').get('preferences').get('theme').put('light');
+
+// Iterate over collections
+shogun.api.node('users').map((user, userId) => {
+  console.log(`User ${userId}:`, user);
+});
+
+// Complex chaining
+await shogun.api.node('projects').get('my-app').get('tasks').get('1').put({
+  title: 'Implement authentication',
+  status: 'completed',
+  assignee: 'alice'
+});
+```
+
+### 2. **Simplified Chaining Wrapper**
+
+Use `chain()` for simplified chaining with error handling:
+
+```typescript
+// Simplified chaining with built-in error handling
+const success = await shogun.api.chain('users').get('alice').get('settings').put({
+  notifications: true,
+  privacy: 'private'
+});
+
+if (success) {
+  console.log('Settings saved successfully');
+}
+
+// Read with simplified chaining
+const settings = await shogun.api.chain('users').get('alice').get('settings').once();
+```
+
+### 3. **Get Gun Node for Advanced Operations**
+
+Use `getNode()` for advanced Gun.js operations:
+
+```typescript
+// Get node for advanced operations
+const usersNode = shogun.api.getNode('users');
+
+// Use all Gun.js methods
+usersNode.map((user, userId) => {
+  console.log(`Processing user ${userId}`);
+  return user;
+});
+
+// Chain from the node
+const aliceProfile = await usersNode.get('alice').get('profile').once();
+```
+
+### Chaining Examples
+
+```typescript
+// User management system
+await shogun.api.node('users').get('alice').put({
+  profile: {
+    name: 'Alice',
+    email: 'alice@example.com'
+  },
+  settings: {
+    theme: 'dark',
+    notifications: true
+  },
+  posts: {
+    '1': { title: 'Hello World', content: 'My first post' },
+    '2': { title: 'GunDB is awesome', content: 'Learning decentralized storage' }
+  }
+});
+
+// Blog system
+await shogun.api.node('blog').get('posts').get('2024-01-15').put({
+  title: 'Getting Started with Shogun Core',
+  author: 'alice',
+  content: 'Shogun Core makes decentralized apps easy...',
+  tags: ['tutorial', 'decentralized', 'web3'],
+  comments: {
+    '1': { author: 'bob', text: 'Great tutorial!' },
+    '2': { author: 'charlie', text: 'Very helpful, thanks!' }
+  }
+});
+
+// E-commerce system
+await shogun.api.node('shop').get('products').get('laptop-001').put({
+  name: 'Gaming Laptop',
+  price: 1299.99,
+  stock: 15,
+  reviews: {
+    '1': { user: 'alice', rating: 5, comment: 'Amazing performance!' },
+    '2': { user: 'bob', rating: 4, comment: 'Good value for money' }
+  }
+});
+
+// Read complex nested data
+const product = await shogun.api.node('shop').get('products').get('laptop-001').once();
+console.log('Product:', product.name);
+console.log('Reviews:', product.reviews);
+
+// Update nested data
+await shogun.api.node('shop').get('products').get('laptop-001').get('stock').put(12);
+```
+
+### Best Practices for Chaining
+
+1. **Use `node()` for most operations** - It provides full Gun.js functionality
+2. **Use `chain()` for simplified error handling** - Good for beginners
+3. **Use `getNode()` for advanced operations** - When you need Gun.js methods like `.map()`
+4. **Keep paths descriptive** - Use meaningful path segments like `users/alice/profile`
+5. **Handle errors appropriately** - Chaining operations can fail, always check results
+
 ## Plugin Authentication APIs
 
 Shogun Core provides a unified plugin system for different authentication methods. Each plugin implements standardized `login()` and `signUp()` methods that return consistent `AuthResult` and `SignUpResult` objects.
@@ -601,6 +750,11 @@ You can also use Shogun Core directly in the browser by including it from a CDN.
 - `set<T>(path: string, data: T): Promise<boolean>` - Update data at path
 - `remove(path: string): Promise<boolean>` - Remove data from path
 
+#### Advanced Chaining Operations (NEW!)
+- `node(path: string): GunNode` - Get Gun node for direct chaining (recommended)
+- `chain(path: string): ChainingWrapper` - Get simplified chaining wrapper
+- `getNode(path: string): GunNode` - Get Gun node for advanced operations like .map()
+
 #### User Space Operations
 - `putUserData<T>(path: string, data: T): Promise<boolean>` - Store user-specific data
 - `getUserData<T>(path: string): Promise<T | null>` - Get user-specific data

package/dist/browser/shogun-core.js

@@ -89704,6 +89704,58 @@ class SimpleGunAPI {
     getNode(path) {
         return this.db.get(path);
     }
+    // Get Gun node for direct chaining - returns the actual Gun node for full chaining support
+    node(path) {
+        return this.db.get(path);
+    }
+    // Get Gun node with chaining support - returns a wrapper that supports chaining
+    chain(path) {
+        const node = this.db.get(path);
+        return {
+            get: (subPath) => this.chain(`${path}/${subPath}`),
+            put: async (data) => {
+                try {
+                    const result = await this.db.put(path, data);
+                    return result.success;
+                }
+                catch (error) {
+                    console.warn(`Failed to put data to ${path}:`, error);
+                    return false;
+                }
+            },
+            set: async (data) => {
+                try {
+                    const result = await this.db.set(path, data);
+                    return result.success;
+                }
+                catch (error) {
+                    console.warn(`Failed to set data to ${path}:`, error);
+                    return false;
+                }
+            },
+            once: async () => {
+                try {
+                    return await this.db.getData(path);
+                }
+                catch (error) {
+                    console.warn(`Failed to get data from ${path}:`, error);
+                    return null;
+                }
+            },
+            then: async () => {
+                try {
+                    return await this.db.getData(path);
+                }
+                catch (error) {
+                    console.warn(`Failed to get data from ${path}:`, error);
+                    return null;
+                }
+            },
+            map: (callback) => {
+                return node.map ? node.map(callback) : null;
+            },
+        };
+    }
     // Simple put - returns success boolean
     async put(path, data) {
         try {