shogun-core 6.4.4 → 6.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. package/README.md +137 -4
  2. package/dist/browser/shogun-core.js +1697 -49
  3. package/dist/browser/shogun-core.js.map +1 -1
  4. package/dist/src/examples/auth-test.js +9 -6
  5. package/dist/src/gundb/db-holster.js +1146 -0
  6. package/dist/src/gundb/db.js +4 -9
  7. package/dist/src/gundb/index.js +2 -0
  8. package/dist/src/gundb/rxjs-holster.js +367 -0
  9. package/dist/src/index.js +3 -1
  10. package/dist/src/managers/CoreInitializer.js +169 -37
  11. package/dist/tsconfig.tsbuildinfo +1 -1
  12. package/dist/types/src/core.d.ts +2 -1
  13. package/dist/types/src/gundb/db-holster.d.ts +197 -0
  14. package/dist/types/src/gundb/db.d.ts +4 -8
  15. package/dist/types/src/gundb/index.d.ts +2 -0
  16. package/dist/types/src/gundb/rxjs-holster.d.ts +84 -0
  17. package/dist/types/src/index.d.ts +3 -1
  18. package/dist/types/src/interfaces/shogun.d.ts +4 -2
  19. package/dist/types/src/managers/CoreInitializer.d.ts +6 -2
  20. package/package.json +1 -1
package/README.md CHANGED
@@ -6,12 +6,15 @@
6
6
 
7
7
  ## Overview
8
8
 
9
- Shogun Core is a comprehensive SDK for building decentralized applications (dApps) that simplifies authentication, wallet management, and decentralized data storage. It combines GunDB's peer-to-peer networking with modern authentication standards and blockchain integration.
9
+ Shogun Core is a comprehensive SDK for building decentralized applications (dApps) that simplifies authentication, wallet management, and decentralized data storage. It combines GunDB's or Holster's peer-to-peer networking with modern authentication standards and blockchain integration.
10
+
11
+ **Now supports both Gun and Holster!** You can use either database backend - Gun for maximum compatibility or Holster for modern ES modules and improved performance.
10
12
 
11
13
  ## Features
12
14
 
13
15
  - 🔐 **Multiple Authentication Methods**: Password, WebAuthn (biometrics), Web3 (MetaMask), Nostr, ZK-Proof (anonymous)
14
- - 🌐 **Decentralized Storage**: Built on GunDB for peer-to-peer data synchronization
16
+ - 🌐 **Decentralized Storage**: Built on GunDB or Holster for peer-to-peer data synchronization
17
+ - 🔄 **Dual Database Support**: Use Gun (maximum compatibility) or Holster (modern ES modules, improved performance)
15
18
  - 🔌 **Plugin System**: Extensible architecture with built-in plugins
16
19
  - 💼 **Smart Wallet**: Account Abstraction with multi-sig, social recovery, and batch transactions
17
20
  - 📱 **Reactive Programming**: RxJS integration for real-time data streams
@@ -28,6 +31,8 @@ yarn add shogun-core
28
31
 
29
32
  ## Quick Start
30
33
 
34
+ ### Using Gun (Default)
35
+
31
36
  ```typescript
32
37
  import { ShogunCore } from "shogun-core";
33
38
  import Gun from "gun";
@@ -68,6 +73,38 @@ const smartWalletPlugin = new SmartWalletPlugin({
68
73
  shogun.register(smartWalletPlugin);
69
74
  ```
70
75
 
76
+ ### Using Holster (Alternative)
77
+
78
+ ```typescript
79
+ import { ShogunCore } from "shogun-core";
80
+ import Holster from "@mblaney/holster";
81
+
82
+ // Create Holster instance first
83
+ const holster = Holster({
84
+ peers: ['ws://localhost:8765']
85
+ });
86
+
87
+ // Initialize Shogun Core with the Holster instance
88
+ const shogun = new ShogunCore({
89
+ holsterInstance: holster, // Use Holster instead of Gun
90
+
91
+ // Enable authentication plugins (same as Gun)
92
+ web3: { enabled: true },
93
+ webauthn: {
94
+ enabled: true,
95
+ rpName: "My Awesome App",
96
+ rpId: window.location.hostname,
97
+ },
98
+ nostr: { enabled: true },
99
+ zkproof: {
100
+ enabled: true,
101
+ defaultGroupId: "my-app-users",
102
+ },
103
+ });
104
+
105
+ // All other APIs work the same way!
106
+ ```
107
+
71
108
  ## Basic Database Operations
72
109
 
73
110
  ```typescript
@@ -253,6 +290,8 @@ if (result.success) {
253
290
 
254
291
  ## Browser Usage (CDN)
255
292
 
293
+ ### With Gun
294
+
256
295
  ```html
257
296
  <!DOCTYPE html>
258
297
  <html>
@@ -288,6 +327,42 @@ if (result.success) {
288
327
  </html>
289
328
  ```
290
329
 
330
+ ### With Holster (ES Modules)
331
+
332
+ ```html
333
+ <!DOCTYPE html>
334
+ <html>
335
+ <head>
336
+ <title>Shogun Core with Holster</title>
337
+ </head>
338
+ <body>
339
+ <h1>My dApp</h1>
340
+ <script type="module">
341
+ import Holster from 'https://cdn.jsdelivr.net/npm/@mblaney/holster/build/holster.js';
342
+ import { ShogunCore } from 'https://cdn.jsdelivr.net/npm/shogun-core/dist/src/index.js';
343
+
344
+ // Create Holster instance
345
+ const holster = Holster({
346
+ peers: ['ws://localhost:8765']
347
+ });
348
+
349
+ // Initialize Shogun Core
350
+ const shogunCore = new ShogunCore({
351
+ holsterInstance: holster,
352
+ web3: { enabled: true },
353
+ webauthn: {
354
+ enabled: true,
355
+ rpName: "My Browser dApp",
356
+ rpId: window.location.hostname,
357
+ },
358
+ });
359
+
360
+ console.log("Shogun Core initialized with Holster!", shogunCore);
361
+ </script>
362
+ </body>
363
+ </html>
364
+ ```
365
+
291
366
  ## Event System
292
367
 
293
368
  ```typescript
@@ -311,11 +386,33 @@ shogun.on("error", (error) => {
311
386
  });
312
387
  ```
313
388
 
389
+ ## Database Backend: Gun vs Holster
390
+
391
+ Shogun Core supports both Gun and Holster as database backends. Choose based on your needs:
392
+
393
+ ### Gun (Default)
394
+ - **Pros**: Maximum compatibility, large ecosystem, battle-tested
395
+ - **Cons**: Older codebase, CommonJS modules
396
+ - **Best for**: Existing projects, maximum compatibility
397
+
398
+ ### Holster
399
+ - **Pros**: Modern ES modules, improved performance, cleaner API
400
+ - **Cons**: Newer project, smaller ecosystem
401
+ - **Best for**: New projects, modern build systems, performance-critical apps
402
+
403
+ **Note**: The API is identical regardless of which backend you choose. Shogun Core handles all the differences internally.
404
+
405
+ ### Differences to be aware of:
406
+ - **Pair-based authentication**: Currently only supported with Gun (username/password works with both)
407
+ - **Event system**: Gun has native events, Holster uses polling (handled automatically)
408
+ - **Chaining API**: Gun uses `.get().get()`, Holster uses `.get().next()` (handled automatically via proxy)
409
+
314
410
  ## Configuration Options
315
411
 
316
412
  ```typescript
317
413
  interface ShogunCoreConfig {
318
- gunInstance: IGunInstance<any>; // Required: existing Gun instance
414
+ gunInstance?: IGunInstance<any>; // Optional: existing Gun instance (required if holsterInstance not provided)
415
+ holsterInstance?: any; // Optional: existing Holster instance (required if gunInstance not provided)
319
416
 
320
417
  // Plugin configurations
321
418
  webauthn?: {
@@ -359,7 +456,43 @@ interface ShogunCoreConfig {
359
456
  }
360
457
  ```
361
458
 
362
- **Note**: `SmartWalletPlugin` must be registered separately using `shogun.register()` as it's not included in the main configuration.
459
+ **Note**:
460
+ - Either `gunInstance` or `holsterInstance` must be provided (but not both)
461
+ - `SmartWalletPlugin` must be registered separately using `shogun.register()` as it's not included in the main configuration
462
+
463
+ ## Migration Guide
464
+
465
+ ### From Gun to Holster
466
+
467
+ If you're currently using Gun and want to switch to Holster:
468
+
469
+ 1. **Install Holster**:
470
+ ```bash
471
+ npm install @mblaney/holster
472
+ # or
473
+ yarn add @mblaney/holster
474
+ ```
475
+
476
+ 2. **Update your initialization**:
477
+ ```typescript
478
+ // Before (Gun)
479
+ import Gun from "gun";
480
+ const gun = Gun({ peers: [...] });
481
+ const shogun = new ShogunCore({ gunInstance: gun });
482
+
483
+ // After (Holster)
484
+ import Holster from "@mblaney/holster";
485
+ const holster = Holster({ peers: [...] });
486
+ const shogun = new ShogunCore({ holsterInstance: holster });
487
+ ```
488
+
489
+ 3. **That's it!** All other code remains the same. The API is identical.
490
+
491
+ ### Limitations when using Holster
492
+
493
+ - Pair-based authentication (`loginWithPair()`) is not yet supported - use username/password instead
494
+ - Some advanced Gun features may not be available
495
+ - Event system uses polling instead of native events (handled automatically)
363
496
 
364
497
  ## Testing
365
498