holosphere 1.1.10 → 1.1.12

package/examples/federation.js

@@ -1,115 +1,109 @@
 /**
- * Organization Federation Example for HoloSphere
+ * Organization Federation Example for HoloSphere (Updated API)
  * 
  * This example demonstrates a real-world use case where a tech team creates tasks
- * that are federated to the parent organization for visibility.
+ * that are automatically federated to the parent organization for visibility using
+ * the latest HoloSphere federation features.
  */
 
-import HoloSphere from './holosphere.js';
+import HoloSphere from '../holosphere.js';
 
 async function organizationFederationExample() {
-  const holoSphere = new HoloSphere('organization-example');
+  const holoSphere = new HoloSphere('organization-example-updated');
   
   try {
-    console.log('Starting Organization Federation Example...');
+    console.log('Starting Organization Federation Example (Updated API)...');
     
-    // Define our spaces/holons
-    const orgHolon = 'acme-organization';
-    const techTeamHolon = 'acme-tech-team';
+    // Define unique names for this run to avoid conflicts
+    const runId = Date.now();
+    const orgHolon = `acme-org-${runId}`;
+    const techTeamHolon = `acme-tech-${runId}`;
     
-    // Step 1: Create federation relationship between tech team and organization
+    // Step 1: Create federation relationship (bidirectional by default)
     console.log('\nStep 1: Creating federation relationship...');
-    
-    await holoSphere.federate(techTeamHolon, orgHolon);
-    console.log('Federation created between tech team and organization');
-    
-    // Step 2: Set up bidirectional notification settings (critical!)
-    console.log('\nStep 2: Setting up bidirectional notification...');
-    
-    // First set up tech team to notify organization
-    const techTeamFedSettings = await holoSphere.getGlobal('federation', techTeamHolon);
-    if (techTeamFedSettings) {
-      techTeamFedSettings.notify = techTeamFedSettings.notify || [];
-      if (!techTeamFedSettings.notify.includes(orgHolon)) {
-        techTeamFedSettings.notify.push(orgHolon);
-        await holoSphere.putGlobal('federation', techTeamFedSettings);
-        console.log('Tech team set to notify organization');
-      }
-    }
-    
-    // Then set up organization to notify tech team (if needed)
-    const orgFedSettings = await holoSphere.getGlobal('federation', orgHolon);
-    if (orgFedSettings) {
-      orgFedSettings.notify = orgFedSettings.notify || [];
-      if (!orgFedSettings.notify.includes(techTeamHolon)) {
-        orgFedSettings.notify.push(techTeamHolon);
-        await holoSphere.putGlobal('federation', orgFedSettings);
-        console.log('Organization set to notify tech team');
-      }
+    // The `federate` method automatically sets up bidirectional notifications when `bidirectional` is true (default).
+    const federateResult = await holoSphere.federate(techTeamHolon, orgHolon); 
+    if (!federateResult) {
+        throw new Error('Federation setup failed.');
     }
+    console.log(`Federation created between ${techTeamHolon} and ${orgHolon}`);
     
-    // Step 3: Verify federation is set up properly
-    console.log('\nStep 3: Verifying federation setup...');
-    
+    // Allow a moment for GunDB propagation of federation settings
+    await new Promise(resolve => setTimeout(resolve, 1500)); 
+
+    // Step 2: Verify federation is set up properly
+    console.log('\nStep 2: Verifying federation setup...');
     const techTeamFedInfo = await holoSphere.getFederation(techTeamHolon);
-    console.log('Tech team federation info:', techTeamFedInfo);
+    console.log(`Tech team (${techTeamHolon}) federation info:`, techTeamFedInfo);
+    if (!techTeamFedInfo?.federation?.includes(orgHolon)) {
+        console.warn('Warning: Organization holon not found in tech team federation list.');
+    }
     
-    // Step 4: Create a task in the tech team holon
-    console.log('\nStep 4: Creating a task in the tech team holon...');
+    const orgFedInfo = await holoSphere.getFederation(orgHolon);
+    console.log(`Organization (${orgHolon}) federation info:`, orgFedInfo);
+    if (!orgFedInfo?.notify?.includes(techTeamHolon)) {
+        console.warn('Warning: Tech team holon not found in organization notify list.');
+    }
+
+    // Step 3: Create a task in the tech team holon
+    // The `put` method automatically propagates data to federated holons by default (`autoPropagate: true`).
+    console.log('\nStep 3: Creating a task in the tech team holon (will auto-propagate)...');
     
     const task = {
-      id: 'task-123',
+      id: `task-${runId}-123`,
       title: 'Implement new authentication system',
       description: 'Replace the current auth system with OAuth2',
       assignee: 'dev@example.com',
       status: 'in_progress',
       priority: 'high',
-      dueDate: '2023-12-31',
+      dueDate: '2024-12-31',
       createdAt: new Date().toISOString(),
       tags: ['security', 'infrastructure']
     };
     
-    // Store the task in the tech team holon
-    await holoSphere.put(techTeamHolon, 'tasks', task);
-    console.log('Task created in tech team holon:', task.id);
-    
-    // Step 5: Propagate the task to the organization holon
-    console.log('\nStep 5: Propagating task to organization holon...');
-    
-    await holoSphere.propagate(techTeamHolon, 'tasks', task);
-    console.log('Task propagated to organization holon');
-    
-    // Step 6: Allow time for propagation
-    console.log('\nStep 6: Waiting for propagation to complete...');
-    await new Promise(resolve => setTimeout(resolve, 1000));
+    // Store the task - it will be automatically propagated to orgHolon due to federation
+    const putResult = await holoSphere.put(techTeamHolon, 'tasks', task);
+    console.log(`Task created in ${techTeamHolon}: ${task.id}. Propagation result:`, putResult.propagationResult);
+    if (putResult.propagationResult?.errors > 0) {
+      console.warn('Warning: Auto-propagation reported errors.');
+    }
+
+    // Step 4: Allow time for propagation via put
+    console.log('\nStep 4: Waiting for auto-propagation to complete...');
+    await new Promise(resolve => setTimeout(resolve, 1500)); 
     
-    // Step 7: Verify task in both holons
-    console.log('\nStep 7: Verifying task is in both holons...');
+    // Step 5: Verify task in both holons
+    console.log('\nStep 5: Verifying task is in both holons...');
     
-    // Check tech team holon directly
-    const techTeamTask = await holoSphere.get(techTeamHolon, 'tasks', 'task-123');
-    console.log('Task in tech team holon:', techTeamTask ? 'Found' : 'Not found');
+    // Check tech team holon directly (original data)
+    const techTeamTask = await holoSphere.get(techTeamHolon, 'tasks', task.id);
+    console.log(`Task in tech team holon (${techTeamHolon}):`, techTeamTask ? 'Found' : 'Not found');
     if (techTeamTask) console.log('Tech team task status:', techTeamTask.status);
     
-    // Check organization holon directly
-    const orgTask = await holoSphere.get(orgHolon, 'tasks', 'task-123');
-    console.log('Task in organization holon:', orgTask ? 'Found' : 'Not found');
+    // Check organization holon directly (should have a resolved reference)
+    const orgTask = await holoSphere.get(orgHolon, 'tasks', task.id);
+    console.log(`Task in organization holon (${orgHolon}):`, orgTask ? 'Found' : 'Not found');
     if (orgTask) {
       console.log('Organization task status:', orgTask.status);
-      console.log('Federation metadata:', orgTask.federation);
+      // Check if it's a resolved reference
+      console.log('Is resolved reference:', !!orgTask._federation?.resolved); 
+    } else {
+      console.warn(`Task ${task.id} not found in organization holon ${orgHolon}. Propagation might have failed or is slow.`);
     }
     
-    // Step 8: Use getFederated to view all tasks across holons
-    console.log('\nStep 8: Using getFederated to view all tasks...');
+    // Step 6: Use getFederated to view all tasks from the organization's perspective
+    console.log('\nStep 6: Using getFederated to view all tasks...');
     
     const allOrgTasks = await holoSphere.getFederated(orgHolon, 'tasks');
-    console.log(`Organization holon has access to ${allOrgTasks.length} tasks`);
+    console.log(`Organization holon (${orgHolon}) has access to ${allOrgTasks.length} tasks (via getFederated):`);
+    // console.log(allOrgTasks); // Uncomment to see the full list
     
     const allTechTasks = await holoSphere.getFederated(techTeamHolon, 'tasks');
-    console.log(`Tech team holon has access to ${allTechTasks.length} tasks`);
-    
-    // Step 9: Update the task in tech team and propagate the change
-    console.log('\nStep 9: Updating task in tech team holon...');
+    console.log(`Tech team holon (${techTeamHolon}) has access to ${allTechTasks.length} tasks (via getFederated):`);
+    // console.log(allTechTasks); // Uncomment to see the full list
+
+    // Step 7: Update the task in tech team holon (will also auto-propagate)
+    console.log('\nStep 7: Updating task in tech team holon (will auto-propagate)...');
     
     const updatedTask = {
       ...task,
@@ -117,30 +111,44 @@ async function organizationFederationExample() {
       completedAt: new Date().toISOString()
     };
     
-    await holoSphere.put(techTeamHolon, 'tasks', updatedTask);
-    await holoSphere.propagate(techTeamHolon, 'tasks', updatedTask);
-    console.log('Task updated and propagated');
-    
-    // Step 10: Allow time for propagation
-    console.log('\nStep 10: Waiting for propagation to complete...');
-    await new Promise(resolve => setTimeout(resolve, 1000));
-    
-    // Step 11: Verify updates in both holons
-    console.log('\nStep 11: Verifying updated task in both holons...');
+    // Update the task - the change will be automatically propagated
+    const updateResult = await holoSphere.put(techTeamHolon, 'tasks', updatedTask);
+    console.log(`Task updated in ${techTeamHolon}. Propagation result:`, updateResult.propagationResult);
+    if (updateResult.propagationResult?.errors > 0) {
+      console.warn('Warning: Auto-propagation of update reported errors.');
+    }
     
-    const updatedTechTeamTask = await holoSphere.get(techTeamHolon, 'tasks', 'task-123');
-    console.log('Updated task in tech team holon status:', updatedTechTeamTask?.status);
+    // Step 8: Allow time for update propagation
+    console.log('\nStep 8: Waiting for update propagation...');
+    await new Promise(resolve => setTimeout(resolve, 1500)); 
     
-    const updatedOrgTask = await holoSphere.get(orgHolon, 'tasks', 'task-123');
-    console.log('Updated task in organization holon status:', updatedOrgTask?.status);
+    // Step 9: Verify updates in both holons
+    console.log('\nStep 9: Verifying updated task in both holons...');
     
-    // Step 12: Clean up - remove federation
-    console.log('\nStep 12: Cleaning up - removing federation...');
+    const updatedTechTeamTask = await holoSphere.get(techTeamHolon, 'tasks', task.id);
+    console.log(`Updated task status in tech team holon (${techTeamHolon}):`, updatedTechTeamTask?.status);
     
+    // Get the potentially updated reference in the organization holon
+    const updatedOrgTask = await holoSphere.get(orgHolon, 'tasks', task.id); 
+    console.log(`Updated task status in organization holon (${orgHolon}):`, updatedOrgTask?.status);
+    if (!updatedOrgTask || updatedOrgTask.status !== 'completed') {
+        console.warn(`Updated task status not reflected in organization holon ${orgHolon}. Propagation might have failed or is slow.`);
+    }
+
+    // Step 10: Clean up - remove federation
+    console.log('\nStep 10: Cleaning up - removing federation...');
     await holoSphere.unfederate(techTeamHolon, orgHolon);
-    console.log('Federation removed between tech team and organization');
+    console.log(`Federation removed between ${techTeamHolon} and ${orgHolon}`);
+    
+    // Optional: Clean up data (can be slow and sometimes unreliable in Gun)
+    // console.log('Cleaning up task data...');
+    // await holoSphere.delete(techTeamHolon, 'tasks', task.id);
+    // await holoSphere.delete(orgHolon, 'tasks', task.id); // Delete the reference
+    // await holoSphere.deleteGlobal('federation', techTeamHolon);
+    // await holoSphere.deleteGlobal('federation', orgHolon);
     
     console.log('\nOrganization federation example completed successfully!');
+    
   } catch (error) {
     console.error('Error in organization federation example:', error);
   } finally {

package/examples/hologram-updates-example.js

@@ -0,0 +1,106 @@
+// hologram-updates-example.js
+// Example showing how to use the returned list of updated holograms from put()
+
+import HoloSphere from '../holosphere.js';
+
+async function exampleUsage() {
+    const holosphere = new HoloSphere('example-app', false);
+    
+    try {
+        // 1. Create some original data
+        const originalData = { 
+            id: 'product-123', 
+            name: 'Widget', 
+            price: 19.99,
+            inventory: 100 
+        };
+        
+        console.log('Step 1: Storing original data...');
+        await holosphere.put('store', 'products', originalData);
+        
+        // 2. Create holograms in different locations (maybe for different displays/views)
+        console.log('Step 2: Creating holograms...');
+        const hologram1 = holosphere.createHologram('store', 'products', originalData);
+        const hologram2 = holosphere.createHologram('store', 'products', originalData);
+        
+        await holosphere.put('storefront', 'display', { id: 'featured-product', soul: hologram1.soul });
+        await holosphere.put('warehouse', 'inventory', { id: 'stock-item', soul: hologram2.soul });
+        
+        // Wait for Gun to propagate
+        await new Promise(resolve => setTimeout(resolve, 500));
+        
+        // 3. Update the original data and get the list of updated holograms
+        console.log('Step 3: Updating original data...');
+        const updatedData = { 
+            ...originalData, 
+            price: 17.99,  // Price reduction!
+            inventory: 95, // Some sold
+            lastUpdated: Date.now()
+        };
+        
+        const result = await holosphere.put('store', 'products', updatedData);
+        
+        console.log('PUT Result:', {
+            success: result.success,
+            pathInfo: {
+                holon: result.pathHolon,
+                lens: result.pathLens,
+                key: result.pathKey
+            },
+            updatedHologramsCount: result.updatedHolograms.length
+        });
+        
+        // 4. Process the updated holograms
+        console.log('Step 4: Processing updated holograms...');
+        if (result.updatedHolograms.length > 0) {
+            console.log(`Updated ${result.updatedHolograms.length} holograms:`);
+            
+            for (const hologram of result.updatedHolograms) {
+                console.log(`  - Hologram at ${hologram.holon}/${hologram.lens}/${hologram.key}`);
+                console.log(`    Soul: ${hologram.soul}`);
+                console.log(`    Updated at: ${new Date(hologram.timestamp).toISOString()}`);
+                
+                // Example post-processing: 
+                // You could trigger UI updates, send notifications, update caches, etc.
+                
+                if (hologram.holon === 'storefront') {
+                    console.log('    -> Triggering storefront display refresh');
+                    // triggerStorefrontRefresh(hologram.key);
+                }
+                
+                if (hologram.holon === 'warehouse') {
+                    console.log('    -> Updating warehouse inventory system');
+                    // updateWarehouseInventory(hologram.key);
+                }
+            }
+        } else {
+            console.log('No holograms were updated.');
+        }
+        
+        // 5. Verify the holograms have the updated timestamp
+        console.log('Step 5: Verifying hologram updates...');
+        const storefrontHologram = await holosphere.get('storefront', 'display', 'featured-product', null, { resolveHolograms: false });
+        const warehouseHologram = await holosphere.get('warehouse', 'inventory', 'stock-item', null, { resolveHolograms: false });
+        
+        console.log('Storefront hologram updated field:', storefrontHologram?.updated);
+        console.log('Warehouse hologram updated field:', warehouseHologram?.updated);
+        
+    } catch (error) {
+        console.error('Error in example:', error);
+    } finally {
+        await holosphere.close();
+    }
+}
+
+// Example usage scenarios:
+console.log('=== Hologram Updates Return Value Example ===');
+console.log('This example demonstrates how to use the updatedHolograms return value from put()');
+console.log('to perform post-processing tasks when original data changes.\n');
+
+exampleUsage().then(() => {
+    console.log('\n=== Example completed ===');
+    process.exit(0);
+}).catch(error => {
+    console.error('Example failed:', error);
+    process.exit(1);
+}); 

package/examples/{references.js → holograms.js}

@@ -1,12 +1,12 @@
-import HoloSphere from './holosphere.js';
+import HoloSphere from '../holosphere.js';
 
-async function testReferenceFederation() {
-    console.log('Starting reference federation test...');
-    const holoSphere = new HoloSphere('test-references');
+async function testHologramFederation() {
+    console.log('Starting hologram federation test...');
+    const holoSphere = new HoloSphere('test-holograms');
     
     try {
-        const space1 = 'ref-test-space1';
-        const space2 = 'ref-test-space2';
+        const space1 = 'holo-test-space1';
+        const space2 = 'holo-test-space2';
         
         // Step 1: Create federation with bidirectional notify settings
         console.log('Step 1: Creating federation between spaces...');
@@ -25,19 +25,19 @@ async function testReferenceFederation() {
         // Step 3: Create test data
         console.log('Step 3: Creating test data...');
         const testData = {
-            id: 'ref-test-item',
-            title: 'Reference Test',
+            id: 'holo-test-item',
+            title: 'Hologram Test',
             value: 200,
-            tags: ['test', 'reference']
+            tags: ['test', 'hologram']
         };
         
         // Store data in space1
         await holoSphere.put(space1, 'items', testData);
         
-        // Step 4: Propagate using references
-        console.log('Step 4: Propagating with soul references...');
+        // Step 4: Propagate using holograms
+        console.log('Step 4: Propagating with soul holograms...');
         const propResult = await holoSphere.propagate(space1, 'items', testData, {
-            useReferences: true
+            useHolograms: true
         });
         console.log('Propagation result:', propResult);
         
@@ -45,17 +45,17 @@ async function testReferenceFederation() {
         console.log('Waiting for propagation...');
         await new Promise(resolve => setTimeout(resolve, 1000));
         
-        // Step 5: Verify that the data in space2 is a soul reference
-        console.log('Step 5: Verifying soul reference was created...');
-        const rawRef = await holoSphere.get(space2, 'items', 'ref-test-item', null, {
-            resolveReferences: false
+        // Step 5: Verify that the data in space2 is a soul hologram
+        console.log('Step 5: Verifying soul hologram was created...');
+        const rawHolo = await holoSphere.get(space2, 'items', 'holo-test-item', null, {
+            resolveHolograms: false
         });
         
-        console.log('Raw reference data:', rawRef);
-        console.log('Is soul reference:', !!rawRef?.soul);
+        console.log('Raw hologram data:', rawHolo);
+        console.log('Is soul hologram:', holoSphere.isHologram(rawHolo));
         
-        if (rawRef?.soul) {
-            const soulParts = rawRef.soul.split('/');
+        if (rawHolo?.soul) {
+            const soulParts = rawHolo.soul.split('/');
             console.log('Soul parts:', soulParts);
             console.log('Soul refers to:', {
                 app: soulParts[0], 
@@ -65,9 +65,9 @@ async function testReferenceFederation() {
             });
         }
         
-        // Step 6: Verify reference resolution works
-        console.log('Step 6: Verifying reference resolution...');
-        const resolvedData = await holoSphere.get(space2, 'items', 'ref-test-item');
+        // Step 6: Verify hologram resolution works
+        console.log('Step 6: Verifying hologram resolution...');
+        const resolvedData = await holoSphere.get(space2, 'items', 'holo-test-item');
         console.log('Resolved data:', resolvedData);
         
         // Step 7: Update the original data
@@ -84,14 +84,14 @@ async function testReferenceFederation() {
         console.log('Waiting for update...');
         await new Promise(resolve => setTimeout(resolve, 500));
         
-        // Step 8: Verify update is reflected through the reference
-        console.log('Step 8: Verifying update is reflected in reference...');
-        const reResolvedData = await holoSphere.get(space2, 'items', 'ref-test-item');
+        // Step 8: Verify update is reflected through the hologram
+        console.log('Step 8: Verifying update is reflected in hologram...');
+        const reResolvedData = await holoSphere.get(space2, 'items', 'holo-test-item');
         console.log('Re-resolved data after update:', reResolvedData);
         
         // Step 9: Update directly through origin holon
         console.log('Step 9: Updating through the origin holon...');
-        const originData = await holoSphere.get(space1, 'items', 'ref-test-item');
+        const originData = await holoSphere.get(space1, 'items', 'holo-test-item');
         
         const finalUpdate = {
             ...originData,
@@ -102,27 +102,24 @@ async function testReferenceFederation() {
         await holoSphere.put(space1, 'items', finalUpdate);
         
         // Allow time for update to propagate
-        console.log('Waiting for update to propagate...');
+        console.log('Waiting for final update...');
         await new Promise(resolve => setTimeout(resolve, 500));
         
-        // Step 10: Verify update is visible through the reference
-        console.log('Step 10: Verifying update is visible through the reference...');
-        const originalAfterUpdate = await holoSphere.get(space1, 'items', 'ref-test-item');
-        console.log('Original data after update:', originalAfterUpdate);
+        // Step 10: Verify final update through the hologram in space2
+        console.log('Step 10: Verifying final update is reflected...');
+        const finalResolvedData = await holoSphere.get(space2, 'items', 'holo-test-item');
+        console.log('Final resolved data:', finalResolvedData);
         
-        const refAfterUpdate = await holoSphere.get(space2, 'items', 'ref-test-item');
-        console.log('Reference resolved data after update:', refAfterUpdate);
-        
-        // Step 11: Test manual soul reference resolution
-        console.log('Step 11: Testing manual soul reference resolution...');
+        // Step 11: Test manual soul hologram resolution
+        console.log('Step 11: Testing manual soul hologram resolution...');
         
         // Check what getAll returns
-        console.log('Raw references from getAll in space2:');
+        console.log('Raw holograms from getAll in space2:');
         const allItems = await holoSphere.getAll(space2, 'items');
         console.log('getAll results:', allItems);
         
         if (allItems.length > 0 && allItems[0].soul) {
-            console.log('Found a soul reference, resolving it manually:');
+            console.log('Found a soul hologram, resolving it manually:');
             const soulParts = allItems[0].soul.split('/');
             
             const originHolon = soulParts[1];
@@ -136,29 +133,29 @@ async function testReferenceFederation() {
                 originLens,
                 originKey,
                 null,
-                { resolveReferences: false }
+                { resolveHolograms: false }
             );
-            console.log('Manually resolved reference data:', originalData);
+            console.log('Manually resolved hologram data:', originalData);
         }
         
-        // Test getFederated with soul references
-        console.log('\nTesting getFederated with soul references:');
+        // Test getFederated with holograms
+        console.log('\nTesting getFederated with holograms:');
         const federatedData = await holoSphere.getFederated(space2, 'items', {
-            resolveReferences: true,
+            resolveHolograms: true,
             idField: 'id'
         });
         
         console.log('getFederated results length:', federatedData.length);
         
         // Find the item by ID
-        const federatedItem = federatedData.find(item => item.id === 'ref-test-item');
+        const federatedItem = federatedData.find(item => item.id === 'holo-test-item');
         console.log('Found federated item by ID:', federatedItem);
         
-        // Check if federated data correctly resolves soul references
+        // Check if federated data correctly resolves soul holograms
         if (federatedItem && federatedItem.value === 400 && federatedItem.finalUpdate) {
-            console.log('SUCCESS: getFederated correctly resolved the soul reference!');
+            console.log('SUCCESS: getFederated correctly resolved the soul hologram!');
         } else {
-            console.log('WARNING: getFederated may not be resolving soul references properly');
+            console.log('WARNING: getFederated may not be resolving soul holograms properly');
         }
         
         // Step 12: Clean up
@@ -166,12 +163,13 @@ async function testReferenceFederation() {
         await holoSphere.unfederate(space1, space2);
         await holoSphere.unfederate(space2, space1);
         
-        console.log('Test completed successfully!');
+        console.log('Hologram federation test completed successfully!');
     } catch (error) {
-        console.error('Error in test:', error);
+        console.error('Hologram federation test failed:', error);
     } finally {
         await holoSphere.close();
+        console.log('HoloSphere connection closed.');
     }
 }
 
-testReferenceFederation().catch(console.error); 
+testHologramFederation();