holosphere 1.1.19 → 2.0.0-alpha0

package/tests/unit/federation.test.js

@@ -0,0 +1,234 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import HoloSphere from '../../src/index.js';
+
+describe('Unit: Federation Module', () => {
+  let hs;
+  let sourceHolon;
+  let targetHolon;
+
+  beforeEach(async () => {
+    hs = new HoloSphere({ relays: [], appName: 'test-federation-unit', persistence: false });
+    sourceHolon = await hs.toHolon(37.7749, -122.4194, 10);
+    targetHolon = await hs.toHolon(37.7749, -122.4194, 8);
+  });
+
+  describe('Hologram creation (reference structure)', () => {
+    it('should create hologram with reference structure', async () => {
+      await hs.write(sourceHolon, 'test', { id: 'item-1', value: 'data' });
+
+      await hs.federate(sourceHolon, targetHolon, 'test', {
+        mode: 'reference'
+      });
+
+      // Hologram should reference original data
+      const fedData = await hs.getFederatedData(targetHolon, 'test');
+      expect(Array.isArray(fedData)).toBe(true);
+    });
+
+    it('should include source holon in hologram metadata', async () => {
+      await hs.write(sourceHolon, 'test', { id: 'item-1', value: 'data' });
+      await hs.federate(sourceHolon, targetHolon, 'test');
+
+      const fedData = await hs.getFederatedData(targetHolon, 'test');
+      const hologram = fedData.find(d => d._meta?.source);
+
+      if (hologram) {
+        expect(hologram._meta.source).toBe(sourceHolon);
+      }
+    });
+
+    it('should create hologram not copy in reference mode', async () => {
+      const lensName = 'test-ref-' + Date.now();
+      await hs.write(sourceHolon, lensName, { id: 'item-1', value: 'original' });
+      await hs.federate(sourceHolon, targetHolon, lensName, { mode: 'reference' });
+
+      // Small delay to ensure federation is complete
+      await new Promise(resolve => setTimeout(resolve, 10));
+
+      // Update source
+      await hs.update(sourceHolon, lensName, 'item-1', { value: 'updated' });
+
+      // Small delay to ensure update is complete
+      await new Promise(resolve => setTimeout(resolve, 10));
+
+      // Target should reflect update (reference, not copy)
+      const fedData = await hs.getFederatedData(targetHolon, lensName);
+      const item = fedData.find(d => d.id === 'item-1');
+      expect(item?.value).toBe('updated');
+    });
+  });
+
+  describe('Hologram resolution (dereference)', () => {
+    it('should resolve holograms to actual data', async () => {
+      const lensName = 'test-resolve-' + Date.now();
+      await hs.write(sourceHolon, lensName, { id: 'item-1', value: 'data' });
+      await hs.federate(sourceHolon, targetHolon, lensName);
+
+      // Small delay to ensure federation is complete
+      await new Promise(resolve => setTimeout(resolve, 10));
+
+      const fedData = await hs.getFederatedData(targetHolon, lensName, {
+        resolveHolograms: true
+      });
+
+      const item = fedData.find(d => d.id === 'item-1');
+      expect(item?.value).toBe('data');
+    });
+
+    it('should return hologram references when resolveHolograms is false', async () => {
+      await hs.write(sourceHolon, 'test', { id: 'item-1', value: 'data' });
+      await hs.federate(sourceHolon, targetHolon, 'test');
+
+      const fedData = await hs.getFederatedData(targetHolon, 'test', {
+        resolveHolograms: false
+      });
+
+      // Should return hologram structure, not resolved data
+      expect(Array.isArray(fedData)).toBe(true);
+    });
+  });
+
+  describe('Circular reference detection', () => {
+    it('should detect circular federation references', async () => {
+      const holonA = await hs.toHolon(37.7749, -122.4194, 9);
+      const holonB = await hs.toHolon(40.7128, -74.0060, 9);
+
+      await hs.federate(holonA, holonB, 'test');
+
+      // Circular: B -> A (when A -> B already exists)
+      await hs.federate(holonB, holonA, 'test');
+
+      // Should not cause infinite loop
+      const dataA = await hs.getFederatedData(holonA, 'test');
+      expect(Array.isArray(dataA)).toBe(true);
+    });
+
+    it('should enforce max depth limit (10 levels)', async () => {
+      // Create a chain longer than max depth
+      const holons = [];
+      for (let i = 0; i < 12; i++) {
+        holons.push(await hs.toHolon(37.7749 + i * 0.01, -122.4194, 9));
+      }
+
+      // Create federation chain
+      for (let i = 0; i < holons.length - 1; i++) {
+        await hs.federate(holons[i], holons[i + 1], 'chain');
+      }
+
+      // Should not traverse beyond max depth
+      const lastData = await hs.getFederatedData(holons[holons.length - 1], 'chain');
+      expect(Array.isArray(lastData)).toBe(true);
+    });
+
+    it('should prevent infinite loops in hologram resolution', async () => {
+      const holonA = await hs.toHolon(37.7749, -122.4194, 9);
+      const holonB = await hs.toHolon(40.7128, -74.0060, 9);
+
+      await hs.write(holonA, 'circular', { id: 'a1', ref: 'b1' });
+      await hs.write(holonB, 'circular', { id: 'b1', ref: 'a1' });
+
+      await hs.federate(holonA, holonB, 'circular', { direction: 'bidirectional' });
+
+      // Should handle circular references gracefully
+      await expect(
+        hs.getFederatedData(holonA, 'circular')
+      ).resolves.toBeDefined();
+    });
+  });
+
+  describe('Federation config validation', () => {
+    it('should validate direction option', async () => {
+      await expect(
+        hs.federate(sourceHolon, targetHolon, 'test', { direction: 'outbound', propagateExisting: false })
+      ).resolves.toBe(true);
+
+      await expect(
+        hs.federate(sourceHolon, targetHolon, 'test', { direction: 'inbound', propagateExisting: false })
+      ).resolves.toBe(true);
+
+      await expect(
+        hs.federate(sourceHolon, targetHolon, 'test', { direction: 'bidirectional', propagateExisting: false })
+      ).resolves.toBe(true);
+    });
+
+    it('should throw error for invalid direction', async () => {
+      await expect(
+        hs.federate(sourceHolon, targetHolon, 'test', { direction: 'invalid' })
+      ).rejects.toThrow(Error);
+    });
+
+    it('should validate mode option', async () => {
+      await expect(
+        hs.federate(sourceHolon, targetHolon, 'test', { mode: 'reference', propagateExisting: false })
+      ).resolves.toBe(true);
+
+      await expect(
+        hs.federate(sourceHolon, targetHolon, 'test', { mode: 'copy', propagateExisting: false })
+      ).resolves.toBe(true);
+    });
+
+    it('should throw error for self-federation', async () => {
+      await expect(
+        hs.federate(sourceHolon, sourceHolon, 'test')
+      ).rejects.toThrow(Error);
+    });
+  });
+
+  describe('Inbound/outbound/bidirectional modes', () => {
+    it('should handle outbound federation (source -> target)', async () => {
+      await hs.write(sourceHolon, 'test', { id: 'item-1', value: 'data' });
+
+      await hs.federate(sourceHolon, targetHolon, 'test', {
+        direction: 'outbound'
+      });
+
+      const targetData = await hs.getFederatedData(targetHolon, 'test');
+      expect(targetData.some(d => d.id === 'item-1')).toBe(true);
+    });
+
+    it('should handle inbound federation (target <- source)', async () => {
+      await hs.write(targetHolon, 'test', { id: 'item-1', value: 'data' });
+
+      await hs.federate(sourceHolon, targetHolon, 'test', {
+        direction: 'inbound'
+      });
+
+      const sourceData = await hs.getFederatedData(sourceHolon, 'test');
+      expect(sourceData.some(d => d.id === 'item-1')).toBe(true);
+    });
+
+    it('should handle bidirectional federation (source <-> target)', async () => {
+      // Use unique lens name to avoid interference from other tests
+      const lensName = 'test-bidir-' + Date.now();
+
+      await hs.write(sourceHolon, lensName, { id: 'source-item', value: 'source' });
+      await hs.write(targetHolon, lensName, { id: 'target-item', value: 'target' });
+
+      await hs.federate(sourceHolon, targetHolon, lensName, {
+        direction: 'bidirectional'
+      });
+
+      const sourceData = await hs.getFederatedData(sourceHolon, lensName);
+      const targetData = await hs.getFederatedData(targetHolon, lensName);
+
+      expect(sourceData.some(d => d.id === 'target-item')).toBe(true);
+      expect(targetData.some(d => d.id === 'source-item')).toBe(true);
+    });
+
+    it('should apply filter function in federation', async () => {
+      // Use unique lens name to avoid interference from other tests
+      const lensName = 'test-filter-' + Date.now();
+
+      await hs.write(sourceHolon, lensName, { id: 'item-1', priority: 'high' });
+      await hs.write(sourceHolon, lensName, { id: 'item-2', priority: 'low' });
+
+      await hs.federate(sourceHolon, targetHolon, lensName, {
+        filter: (data) => data.priority === 'high'
+      });
+
+      const targetData = await hs.getFederatedData(targetHolon, lensName);
+      expect(targetData.some(d => d.id === 'item-1')).toBe(true);
+      expect(targetData.some(d => d.id === 'item-2')).toBe(false);
+    });
+  });
+});

package/tests/unit/gun-async.test.js

@@ -0,0 +1,252 @@
+import { describe, it, expect, beforeEach, afterEach, beforeAll } from 'vitest';
+
+// Dynamically import Gun (optional dependency)
+let Gun;
+let gunAvailable = false;
+
+// Import gun-async utilities
+let gunPromise, gunPut, gunMap, gunMapIterator, gunCollect, gunWaitFor, gunBatchGet, gunBatchPut, gunRetry, gunStream;
+
+beforeAll(async () => {
+  try {
+    Gun = (await import('gun')).default;
+    const gunAsync = await import('../../src/storage/gun-async.js');
+    gunPromise = gunAsync.gunPromise;
+    gunPut = gunAsync.gunPut;
+    gunMap = gunAsync.gunMap;
+    gunMapIterator = gunAsync.gunMapIterator;
+    gunCollect = gunAsync.gunCollect;
+    gunWaitFor = gunAsync.gunWaitFor;
+    gunBatchGet = gunAsync.gunBatchGet;
+    gunBatchPut = gunAsync.gunBatchPut;
+    gunRetry = gunAsync.gunRetry;
+    gunStream = gunAsync.gunStream;
+    gunAvailable = true;
+  } catch (e) {
+    console.log('Gun not available, skipping gun-async tests');
+  }
+});
+
+describe('Gun Async Utilities', () => {
+  let gun;
+
+  beforeEach(() => {
+    if (!gunAvailable) return;
+    gun = Gun({ radisk: false, localStorage: false });
+  });
+
+  afterEach(() => {
+    // Cleanup
+  });
+
+  describe('gunPromise', () => {
+    it('should resolve with data from once()', async () => {
+      if (!gunAvailable) return;
+      const testData = { id: 'test1', value: 'hello' };
+      await gunPut(gun.get('test1'), testData);
+
+      const result = await gunPromise(gun.get('test1'));
+      expect(result.id).toBe('test1');
+      expect(result.value).toBe('hello');
+    });
+
+    it('should resolve with null for non-existent data', async () => {
+      if (!gunAvailable) return;
+      const result = await gunPromise(gun.get('nonexistent'));
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('gunPut', () => {
+    it('should write data and resolve ack', async () => {
+      if (!gunAvailable) return;
+      const data = { id: 'test2', name: 'Test' };
+      const ack = await gunPut(gun.get('test2'), data);
+
+      expect(ack).toBeDefined();
+      expect(ack.err).toBeUndefined();
+    });
+
+    it('should reject on write error', async () => {
+      if (!gunAvailable) return;
+      // Gun typically doesn't error on put, but this tests the pattern
+      const data = { id: 'test3' };
+      const ack = await gunPut(gun.get('test3'), data);
+      expect(ack.err).toBeUndefined();
+    });
+  });
+
+  describe('gunMap', () => {
+    it('should collect map items', async () => {
+      if (!gunAvailable) return;
+      const base = gun.get('testmap');
+      await gunPut(base.get('item1'), { id: 'item1', value: 'a' });
+      await gunPut(base.get('item2'), { id: 'item2', value: 'b' });
+      await gunPut(base.get('item3'), { id: 'item3', value: 'c' });
+
+      // Wait a bit for Gun to sync
+      await new Promise((r) => setTimeout(r, 100));
+
+      const items = await gunMap(base, 800);
+
+      // Gun may or may not have items in memory-only mode
+      expect(Object.keys(items).length).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe('gunMapIterator', () => {
+    it('should iterate over map items', async () => {
+      if (!gunAvailable) return;
+      const base = gun.get('testiterator');
+      await gunPut(base.get('a'), { id: 'a', val: 1 });
+      await gunPut(base.get('b'), { id: 'b', val: 2 });
+
+      // Wait for Gun to sync
+      await new Promise((r) => setTimeout(r, 100));
+
+      const items = [];
+      for await (const [key, value] of gunMapIterator(base)) {
+        items.push({ key, value });
+      }
+
+      // Gun may or may not have items in memory-only mode
+      expect(items.length).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe('gunCollect', () => {
+    it('should collect on() stream data', async () => {
+      if (!gunAvailable) return;
+      const base = gun.get('testcollect');
+
+      // Write data
+      await gunPut(base, { id: 'collect1', value: 'test' });
+
+      // Collect updates
+      const results = await gunCollect(base, 300);
+
+      expect(results.length).toBeGreaterThan(0);
+      expect(results[0].data).toBeDefined();
+    });
+  });
+
+  describe('gunWaitFor', () => {
+    it('should resolve when condition is met', async () => {
+      if (!gunAvailable) return;
+      const ref = gun.get('testwait');
+
+      // Start waiting
+      const waitPromise = gunWaitFor(
+        ref,
+        (data) => data && data.ready === true,
+        2000
+      );
+
+      // Set data after a delay
+      setTimeout(async () => {
+        await gunPut(ref, { id: 'testwait', ready: true });
+      }, 100);
+
+      const result = await waitPromise;
+      expect(result.ready).toBe(true);
+    });
+
+    it('should timeout if condition not met', async () => {
+      if (!gunAvailable) return;
+      const ref = gun.get('testtimeout');
+
+      await expect(
+        gunWaitFor(ref, (data) => data && data.never === true, 500)
+      ).rejects.toThrow('Timeout');
+    });
+  });
+
+  describe('gunBatchGet', () => {
+    it('should read multiple paths', async () => {
+      if (!gunAvailable) return;
+      await gunPut(gun.get('batch1'), { id: 'batch1', val: 1 });
+      await gunPut(gun.get('batch2'), { id: 'batch2', val: 2 });
+      await gunPut(gun.get('batch3'), { id: 'batch3', val: 3 });
+
+      const results = await gunBatchGet(gun, ['batch1', 'batch2', 'batch3']);
+
+      expect(results.batch1.id).toBe('batch1');
+      expect(results.batch2.id).toBe('batch2');
+      expect(results.batch3.id).toBe('batch3');
+    });
+  });
+
+  describe('gunBatchPut', () => {
+    it('should write multiple paths', async () => {
+      if (!gunAvailable) return;
+      const data = {
+        batchput1: { id: 'batchput1', val: 'a' },
+        batchput2: { id: 'batchput2', val: 'b' },
+        batchput3: { id: 'batchput3', val: 'c' },
+      };
+
+      const results = await gunBatchPut(gun, data);
+
+      expect(results.batchput1).toBeDefined();
+      expect(results.batchput2).toBeDefined();
+      expect(results.batchput3).toBeDefined();
+
+      // Verify writes
+      const read1 = await gunPromise(gun.get('batchput1'));
+      expect(read1.val).toBe('a');
+    });
+  });
+
+  describe('gunRetry', () => {
+    it('should retry failed operations', async () => {
+      if (!gunAvailable) return;
+      let attempts = 0;
+
+      const operation = async () => {
+        attempts++;
+        if (attempts < 3) {
+          throw new Error('Not ready');
+        }
+        return 'success';
+      };
+
+      const result = await gunRetry(operation, 5, 50);
+      expect(result).toBe('success');
+      expect(attempts).toBe(3);
+    });
+
+    it('should throw after max retries', async () => {
+      if (!gunAvailable) return;
+      const operation = async () => {
+        throw new Error('Always fails');
+      };
+
+      await expect(gunRetry(operation, 2, 10)).rejects.toThrow('Always fails');
+    });
+  });
+
+  describe('gunStream', () => {
+    it('should create async iterable stream', async () => {
+      if (!gunAvailable) return;
+      const ref = gun.get('teststream');
+      const stream = gunStream(ref);
+
+      // Write data
+      setTimeout(async () => {
+        await gunPut(ref, { id: 'stream1', value: 'test' });
+      }, 50);
+
+      setTimeout(() => {
+        stream.stop();
+      }, 300);
+
+      const items = [];
+      for await (const item of stream) {
+        items.push(item);
+        if (items.length >= 1) break; // Prevent infinite loop
+      }
+
+      expect(items.length).toBeGreaterThan(0);
+    });
+  });
+});