npm - holosphere - Versions diffs - 1.1.18 → 1.1.19 - Mend

holosphere 1.1.18 → 1.1.19

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 (8) hide show

package/README.md +173 -2
package/content.js +4 -1
package/holosphere-bundle.esm.js +20157 -18855
package/holosphere-bundle.js +20157 -18855
package/holosphere-bundle.min.js +29 -19
package/holosphere.d.ts +34 -0
package/holosphere.js +57 -5
package/package.json +3 -3

package/README.md CHANGED Viewed

@@ -136,21 +136,135 @@ npm install holosphere
 ## Quick Start
+### Node.js Usage
 ```javascript
 import HoloSphere from 'holosphere';
-// Initialize HoloSphere
+// Initialize HoloSphere with radisk persistence
 const sphere = new HoloSphere('my-app');
-// Store data at a location
+// Configure radisk storage (optional - enabled by default)
+sphere.configureRadisk({
+    file: './my-data',     // Custom storage directory
+    radisk: true,          // Enable disk persistence
+    retry: 3,              // Retry failed operations
+    timeout: 5000          // Operation timeout
+});
+// Store data at a location (persisted to disk)
 const holon = await sphere.getHolon(40.7128, -74.0060, 7); // NYC at resolution 7
 await sphere.put(holon, 'observations', {
     id: 'obs-001',
     temperature: 22.5,
     timestamp: Date.now()
 });
+// Retrieve data (from memory or disk)
+const data = await sphere.get(holon, 'observations', 'obs-001');
+console.log(data);
+// Get radisk statistics
+const stats = sphere.getRadiskStats();
+console.log('Storage stats:', stats);
+```
+### Browser Usage
+HoloSphere works seamlessly in browsers with radisk persistence. The bundle automatically includes radisk support:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>HoloSphere Browser Example</title>
+</head>
+<body>
+    <!-- Load HoloSphere Bundle -->
+    <script src="https://unpkg.com/holosphere@1.1.18/holosphere-bundle.js"></script>
+    <script>
+        // Radisk is enabled by default in browser
+        const sphere = new HoloSphere('browser-app');
+        // Store data (persisted via IndexedDB)
+        async function storeData() {
+            const holon = await sphere.getHolon(40.7128, -74.0060, 7);
+            await sphere.put(holon, 'observations', {
+                id: 'browser-obs-001',
+                temperature: 22.5,
+                timestamp: Date.now()
+            });
+            console.log('Data stored and persisted!');
+        }
+        // Retrieve data (from IndexedDB)
+        async function retrieveData() {
+            const holon = await sphere.getHolon(40.7128, -74.0060, 7);
+            const data = await sphere.get(holon, 'observations', 'browser-obs-001');
+            console.log('Retrieved data:', data);
+        }
+        // Check radisk status
+        const stats = sphere.getRadiskStats();
+        console.log('Radisk stats:', stats);
+    </script>
+</body>
+</html>
 ```
+**Key Browser Features:**
+- ✅ Radisk automatically included in bundle
+- ✅ Data persists across page reloads via IndexedDB
+- ✅ Works offline with local storage
+- ✅ No additional configuration needed
+- ✅ Compatible with all modern browsers
+See `examples/radisk-browser-example.html` for a complete working example.
+### Svelte/SvelteKit Usage
+HoloSphere works seamlessly with Svelte and SvelteKit applications:
+```svelte
+<script>
+  import { onMount } from 'svelte';
+  import { browser } from '$app/environment'; // SvelteKit only
+  import HoloSphere from 'holosphere';
+  let hs = null;
+  async function initHoloSphere() {
+    // Client-side only for SvelteKit
+    if (typeof browser !== 'undefined' && !browser) return;
+    hs = new HoloSphere('my-app', false, null, {
+      radisk: true,
+      file: './app-radata'
+    });
+  }
+  onMount(() => {
+    initHoloSphere();
+  });
+</script>
+<main>
+  <button on:click={() => storeData()} disabled={!hs}>
+    Store Data
+  </button>
+</main>
+```
+**Key Svelte Features:**
+- ✅ Full Svelte and SvelteKit compatibility
+- ✅ SSR-safe initialization
+- ✅ Reactive data binding
+- ✅ Component lifecycle management
+- ✅ Persistent storage across navigation
+See `examples/svelte-holosphere-example.svelte` and `examples/sveltekit-holosphere-example/+page.svelte` for complete examples.
 ## Real-World Examples
 ### Environmental Monitoring System
@@ -444,6 +558,63 @@ await holosphere.updateFederatedMessages('chat1', 'msg1', async (chatId, message
 });
 ```
+## Radisk Storage Configuration
+HoloSphere uses GunDB's radisk module for persistent storage. Data is automatically saved to disk and can survive application restarts.
+### Basic Configuration
+```javascript
+// Configure radisk with custom options
+sphere.configureRadisk({
+    file: './my-data',     // Storage directory
+    radisk: true,          // Enable disk persistence
+    retry: 3,              // Retry failed operations
+    timeout: 5000          // Operation timeout in ms
+});
+```
+### Get Storage Statistics
+```javascript
+const stats = sphere.getRadiskStats();
+console.log(stats);
+// Output:
+// {
+//   enabled: true,
+//   filePath: './my-data',
+//   retry: 3,
+//   timeout: 5000,
+//   until: null,
+//   peers: ['https://gun.holons.io/gun'],
+//   localStorage: false
+// }
+```
+### Radisk Options
+- `file`: Directory for storing data files (default: `'./radata'`)
+- `radisk`: Enable/disable disk persistence (default: `true`)
+- `retry`: Number of retries for failed operations (default: `3`)
+- `timeout`: Operation timeout in milliseconds (default: `5000`)
+- `until`: Timestamp until which to keep data (optional)
+### Data Persistence
+All data stored via HoloSphere is automatically persisted to disk:
+```javascript
+// This data will be saved to disk
+await sphere.put(holon, 'environment', {
+    id: 'reading-001',
+    temperature: 22.5,
+    timestamp: Date.now()
+});
+// Data persists across application restarts
+const data = await sphere.get(holon, 'environment', 'reading-001');
+```
 ## Soul References
 When using the default `useReferences: true` with propagation:

package/content.js CHANGED Viewed

@@ -151,7 +151,10 @@ export async function put(holoInstance, holon, lens, data, password = null, opti
                 const putCallback = async (ack) => {
                     if (ack.err) {
-                        reject(new Error(ack.err));
+                        // Handle the error object properly - ack.err can be either a string or an object
+                        // If it's an object, convert it to JSON string for better error reporting
+                        const errorMessage = typeof ack.err === 'object' ? JSON.stringify(ack.err) : ack.err;
+                        reject(new Error(errorMessage));
                     } else {
                         // --- Start: Hologram Tracking Logic (for data *being put*, if it's a hologram) ---
                         if (isHologram) {