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

holosphere 1.1.19 → 1.1.21

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

package/README.md +2 -173
package/content.js +93 -119
package/global.js +68 -64
package/holosphere-bundle.esm.js +11609 -12218
package/holosphere-bundle.js +11609 -12218
package/holosphere-bundle.min.js +22 -32
package/holosphere.d.ts +16 -19
package/holosphere.js +17 -36
package/package.json +7 -7

package/README.md CHANGED Viewed

@@ -136,135 +136,21 @@ npm install holosphere
 ## Quick Start
-### Node.js Usage
 ```javascript
 import HoloSphere from 'holosphere';
-// Initialize HoloSphere with radisk persistence
+// Initialize HoloSphere
 const sphere = new HoloSphere('my-app');
-// 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)
+// Store data at a location
 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
@@ -558,63 +444,6 @@ 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,10 +151,7 @@ export async function put(holoInstance, holon, lens, data, password = null, opti
                 const putCallback = async (ack) => {
                     if (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));
+                        reject(new Error(ack.err));
                     } else {
                         // --- Start: Hologram Tracking Logic (for data *being put*, if it's a hologram) ---
                         if (isHologram) {
@@ -511,94 +508,110 @@ export async function getAll(holoInstance, holon, lens, password = null) {
         return new Promise((resolve) => {
             const output = new Map();
+            const pendingProcessing = [];
-            const processData = async (data, key) => {
-                if (!data || key === '_') return;
+            const dataPath = password ?
+                user.get('private').get(lens) :
+                holoInstance.gun.get(holoInstance.appname).get(holon).get(lens);
-                try {
-                    const parsed = await holoInstance.parse(data); // Use instance's parse
-                    if (!parsed || !parsed.id) return;
+            // PASS 1: Get shallow node to determine expected item count
+            dataPath.once((data) => {
+                if (!data) {
+                    resolve([]);
+                    return;
+                }
-                    // Check if this is a hologram that needs to be resolved
-                    if (holoInstance.isHologram(parsed)) {
+                // Filter out Gun metadata, null/deleted entries, and Gun soul references
+                const keys = Object.keys(data).filter(key => {
+                    if (key === '_') return false;
+                    const val = data[key];
+                    if (val === null) return false;
+                    // Filter out Gun graph references (sub-nodes)
+                    if (typeof val === 'object' && val['#']) return false;
+                    return true;
+                });
+                const expectedCount = keys.length;
+                if (expectedCount === 0) {
+                    resolve([]);
+                    return;
+                }
+                // PASS 2: Use map().once() to iterate and get full item data
+                let receivedCount = 0;
+                dataPath.map().once(async (itemData, key) => {
+                    if (!itemData || key === '_') {
+                        receivedCount++;
+                        if (receivedCount >= expectedCount) {
+                            await Promise.all(pendingProcessing);
+                            resolve(Array.from(output.values()));
+                        }
+                        return;
+                    }
+                    const processingPromise = (async () => {
                         try {
-                            const resolved = await holoInstance.resolveHologram(parsed, {
-                                followHolograms: true,
-                                maxDepth: 10,
-                                currentDepth: 0
-                            });
+                            const parsed = await holoInstance.parse(itemData);
+                            if (!parsed || !parsed.id) return;
-                            if (resolved === null) {
-                                console.warn(`Broken hologram detected in getAll for key ${key}. Removing it...`);
+                            if (holoInstance.isHologram(parsed)) {
                                 try {
-                                    // Delete the broken hologram
-                                    await holoInstance.delete(holon, lens, key, password);
-                                    console.log(`Successfully removed broken hologram from ${holon}/${lens}/${key}`);
-                                } catch (cleanupError) {
-                                    console.error(`Failed to remove broken hologram at ${holon}/${lens}/${key}:`, cleanupError);
-                                }
-                                return; // Skip adding this item to output
-                            }
+                                    const resolved = await holoInstance.resolveHologram(parsed, {
+                                        followHolograms: true,
+                                        maxDepth: 10,
+                                        currentDepth: 0
+                                    });
-                            if (resolved && resolved !== parsed) {
-                                // Hologram was resolved successfully
-                                if (schema) {
-                                    const valid = holoInstance.validator.validate(schema, resolved);
-                                    if (valid || !holoInstance.strict) {
-                                        output.set(resolved.id, resolved);
+                                    if (resolved === null) {
+                                        console.warn(`Broken hologram detected in getAll for key ${key}. Removing it...`);
+                                        try {
+                                            await holoInstance.delete(holon, lens, key, password);
+                                        } catch (cleanupError) {
+                                            console.error(`Failed to remove broken hologram at ${holon}/${lens}/${key}:`, cleanupError);
+                                        }
+                                        return;
                                     }
-                                } else {
-                                    output.set(resolved.id, resolved);
+                                    if (resolved && resolved !== parsed) {
+                                        if (schema) {
+                                            const valid = holoInstance.validator.validate(schema, resolved);
+                                            if (valid || !holoInstance.strict) {
+                                                output.set(resolved.id, resolved);
+                                            }
+                                        } else {
+                                            output.set(resolved.id, resolved);
+                                        }
+                                        return;
+                                    }
+                                } catch (hologramError) {
+                                    console.error(`Error resolving hologram for key ${key}:`, hologramError);
+                                    return;
                                 }
-                                return;
                             }
-                        } catch (hologramError) {
-                            console.error(`Error resolving hologram for key ${key}:`, hologramError);
-                            return; // Skip this item
-                        }
-                    }
-                    if (schema) {
-                        const valid = holoInstance.validator.validate(schema, parsed);
-                        if (valid || !holoInstance.strict) {
-                            output.set(parsed.id, parsed);
+                            if (schema) {
+                                const valid = holoInstance.validator.validate(schema, parsed);
+                                if (valid || !holoInstance.strict) {
+                                    output.set(parsed.id, parsed);
+                                }
+                            } else {
+                                output.set(parsed.id, parsed);
+                            }
+                        } catch (error) {
+                            console.error('Error processing data:', error);
                         }
-                    } else {
-                        output.set(parsed.id, parsed);
-                    }
-                } catch (error) {
-                    console.error('Error processing data:', error);
-                }
-            };
+                    })();
-            const handleData = async (data) => {
-                if (!data) {
-                    resolve([]);
-                    return;
-                }
-                const initialPromises = [];
-                Object.keys(data)
-                    .filter(key => key !== '_')
-                    .forEach(key => {
-                        initialPromises.push(processData(data[key], key));
-                    });
+                    pendingProcessing.push(processingPromise);
+                    receivedCount++;
-                try {
-                    await Promise.all(initialPromises);
-                    resolve(Array.from(output.values()));
-                } catch (error) {
-                    console.error('Error in getAll:', error);
-                    resolve([]);
-                }
-            };
-            const dataPath = password ?
-                user.get('private').get(lens) :
-                holoInstance.gun.get(holoInstance.appname).get(holon).get(lens);
-            dataPath.once(handleData);
+                    if (receivedCount >= expectedCount) {
+                        await Promise.all(pendingProcessing);
+                        resolve(Array.from(output.values()));
+                    }
+                });
+            });
         });
     } catch (error) {
         console.error('Error in getAll:', error);
@@ -642,57 +655,18 @@ export async function parse(holoInstance, rawData) {
         } else if (rawData._) {
             // Handle potential GunDB metadata remnants (attempt cleanup)
             console.warn('Parsing raw Gun object with metadata (_) - attempting cleanup:', rawData);
-            // Enhanced cleanup for complex GunDB structures
             const potentialData = Object.keys(rawData).reduce((acc, k) => {
                 if (k !== '_') {
-                    // Handle nested raw GunDB nodes
-                    if (rawData[k] && typeof rawData[k] === 'object' && rawData[k]._) {
-                        // Recursively parse nested raw nodes
-                        const parsedNested = parse(holoInstance, rawData[k]);
-                        if (parsedNested !== null) {
-                            acc[k] = parsedNested;
-                        }
-                    } else if (rawData[k] !== null) {
-                        // Only include non-null values
-                        acc[k] = rawData[k];
-                    }
+                    acc[k] = rawData[k];
                 }
                 return acc;
             }, {});
             if (Object.keys(potentialData).length === 0) {
-                console.warn('Raw Gun object had only metadata (_) or null values, returning null.');
-                return null;
-            }
-            // Additional validation: check if the cleaned object has meaningful data
-            const hasValidData = Object.values(potentialData).some(value =>
-                value !== null && value !== undefined &&
-                (typeof value !== 'object' || Object.keys(value).length > 0)
-            );
-            if (!hasValidData) {
-                console.warn('Cleaned Gun object has no valid data, returning null.');
+                console.warn('Raw Gun object had only metadata (_), returning null.');
                 return null;
             }
             return potentialData; // Return cleaned-up object
         } else {
-            // Check for objects that might be arrays of raw GunDB nodes
-            if (Array.isArray(rawData)) {
-                const cleanedArray = rawData
-                    .map(item => parse(holoInstance, item))
-                    .filter(item => item !== null);
-                if (cleanedArray.length === 0) {
-                    console.warn('Array contained only invalid/raw GunDB nodes, returning null.');
-                    return null;
-                }
-                return cleanedArray;
-            }
             // Assume it's a regular plain object
             return rawData;
         }

package/global.js CHANGED Viewed

@@ -320,86 +320,90 @@ export async function getAllGlobal(holoInstance, tableName, password = null) {
         }
         return new Promise((resolve) => {
-            let output = [];
-            let isResolved = false;
-            let timeout = setTimeout(() => {
-                if (!isResolved) {
-                    isResolved = true;
-                    resolve(output);
-                }
-            }, 5000);
+            const output = [];
+            const pendingProcessing = [];
-            const handleData = async (data) => {
+            const dataPath = password ?
+                user.get('private').get(tableName) :
+                holoInstance.gun.get(holoInstance.appname).get(tableName);
+            // PASS 1: Get shallow node to determine expected item count
+            dataPath.once((data) => {
                 if (!data) {
-                    clearTimeout(timeout);
-                    isResolved = true;
                     resolve([]);
                     return;
                 }
-                const keys = Object.keys(data).filter(key => key !== '_');
-                const promises = keys.map(key =>
-                    new Promise(async (resolveItem) => {
-                        const itemPath = password ?
-                            user.get('private').get(tableName).get(key) :
-                            holoInstance.gun.get(holoInstance.appname).get(tableName).get(key);
+                // Filter out Gun metadata, null/deleted entries, and Gun soul references
+                const keys = Object.keys(data).filter(key => {
+                    if (key === '_') return false;
+                    const val = data[key];
+                    if (val === null) return false;
+                    // Filter out Gun graph references (sub-nodes)
+                    if (typeof val === 'object' && val['#']) return false;
+                    return true;
+                });
+                const expectedCount = keys.length;
-                        const itemData = await new Promise(resolveData => {
-                            itemPath.once(resolveData);
-                        });
+                if (expectedCount === 0) {
+                    resolve([]);
+                    return;
+                }
-                        if (itemData) {
-                            try {
-                                const parsed = await holoInstance.parse(itemData); // Use instance's parse
-                                if (parsed) {
-                                    // Check if this is a hologram that needs to be resolved
-                                    if (holoInstance.isHologram(parsed)) { // Use instance's isHologram
-                                        const resolved = await holoInstance.resolveHologram(parsed, { // Use instance's resolveHologram
-                                            followHolograms: true // Always follow holograms
-                                        });
+                // PASS 2: Use map().once() to iterate and get full item data
+                let receivedCount = 0;
-                                        if (resolved === null) {
-                                            try {
-                                                await holoInstance.deleteGlobal(tableName, key, password); // Use instance's deleteGlobal
-                                            } catch (deleteError) {
-                                                console.error(`Failed to delete invalid global hologram at ${tableName}/${key}:`, deleteError);
-                                            }
-                                            resolveItem();
-                                            return;
-                                        }
+                dataPath.map().once(async (itemData, key) => {
+                    if (!itemData || key === '_') {
+                        receivedCount++;
+                        if (receivedCount >= expectedCount) {
+                            await Promise.all(pendingProcessing);
+                            resolve(output);
+                        }
+                        return;
+                    }
-                                        if (resolved !== parsed) {
-                                            // Hologram was resolved successfully
-                                            output.push(resolved);
-                                        } else {
-                                            // If resolution didn't change it (e.g., circular ref guard), push original parsed (which is a hologram)
-                                            output.push(parsed);
-                                        }
-                                    } else {
-                                        output.push(parsed);
+                    const processingPromise = (async () => {
+                        try {
+                            const parsed = await holoInstance.parse(itemData);
+                            if (!parsed) return;
+                            if (holoInstance.isHologram(parsed)) {
+                                const resolved = await holoInstance.resolveHologram(parsed, {
+                                    followHolograms: true
+                                });
+                                if (resolved === null) {
+                                    try {
+                                        await holoInstance.deleteGlobal(tableName, key, password);
+                                    } catch (deleteError) {
+                                        console.error(`Failed to delete invalid global hologram at ${tableName}/${key}:`, deleteError);
                                     }
+                                    return;
                                 }
-                            } catch (error) {
-                                console.error('Error parsing data:', error);
+                                if (resolved !== parsed) {
+                                    output.push(resolved);
+                                } else {
+                                    output.push(parsed);
+                                }
+                            } else {
+                                output.push(parsed);
                             }
+                        } catch (error) {
+                            console.error('Error parsing data:', error);
                         }
-                        resolveItem();
-                    })
-                );
-                await Promise.all(promises);
-                clearTimeout(timeout);
-                if (!isResolved) {
-                    isResolved = true;
-                    resolve(output);
-                }
-            };
+                    })();
-            const dataPath = password ?
-                user.get('private').get(tableName) :
-                holoInstance.gun.get(holoInstance.appname).get(tableName);
+                    pendingProcessing.push(processingPromise);
+                    receivedCount++;
-            dataPath.once(handleData);
+                    if (receivedCount >= expectedCount) {
+                        await Promise.all(pendingProcessing);
+                        resolve(output);
+                    }
+                });
+            });
         });
     } catch (error) {
         console.error('Error in getAllGlobal:', error);