holosphere 1.1.20 → 2.0.0-alpha1

package/tests/unit/performance/benchmark.test.js

@@ -0,0 +1,85 @@
+/**
+ * Performance Benchmarks
+ * Tests initialization, write, read, subscription overhead, hologram resolution
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import HoloSphere from '../../../src/index.js';
+
+describe('Performance Benchmarks', () => {
+  let hs;
+
+  beforeAll(() => {
+    hs = new HoloSphere({ relays: [], appName: 'perf-test', logLevel: 'ERROR' });
+  });
+
+  it('initialization should complete in <50ms (without crypto)', () => {
+    const start = performance.now();
+    const instance = new HoloSphere({ relays: [], appName: 'test', logLevel: 'ERROR' });
+    const duration = performance.now() - start;
+
+    expect(instance).toBeDefined();
+    expect(duration).toBeLessThan(50);
+    console.log(`✓ Initialization: ${duration.toFixed(2)}ms`);
+  });
+
+  it('write operation should complete in <100ms (avg)', async () => {
+    const holonId = await hs.toHolon(37.7749, -122.4194, 9);
+    const iterations = 10;
+    const durations = [];
+
+    for (let i = 0; i < iterations; i++) {
+      const start = performance.now();
+      await hs.write(holonId, 'perf', { id: `item-${i}`, value: i });
+      const duration = performance.now() - start;
+      durations.push(duration);
+    }
+
+    const avg = durations.reduce((a, b) => a + b, 0) / iterations;
+    expect(avg).toBeLessThan(100);
+    console.log(`✓ Write (avg): ${avg.toFixed(2)}ms`);
+  });
+
+  it('read operation should complete in <10ms (avg)', async () => {
+    const holonId = await hs.toHolon(37.7749, -122.4194, 9);
+    const iterations = 10;
+    const durations = [];
+
+    // Pre-write data
+    await hs.write(holonId, 'perf', { id: 'read-test', value: 42 });
+
+    for (let i = 0; i < iterations; i++) {
+      const start = performance.now();
+      await hs.read(holonId, 'perf', 'read-test');
+      const duration = performance.now() - start;
+      durations.push(duration);
+    }
+
+    const avg = durations.reduce((a, b) => a + b, 0) / iterations;
+    expect(avg).toBeLessThan(10);
+    console.log(`✓ Read (avg): ${avg.toFixed(2)}ms`);
+  });
+
+  it('subscription overhead should be <5ms', () => {
+    const holonId = '8928342e20fffff'; // Pre-computed H3
+    const callback = () => {};
+
+    const start = performance.now();
+    const sub = hs.subscribe(holonId, 'perf', callback);
+    const duration = performance.now() - start;
+
+    expect(duration).toBeLessThan(5);
+    console.log(`✓ Subscription overhead: ${duration.toFixed(2)}ms`);
+
+    sub.unsubscribe();
+  });
+
+  it('H3 conversion should complete in <5ms', async () => {
+    const start = performance.now();
+    await hs.toHolon(37.7749, -122.4194, 9);
+    const duration = performance.now() - start;
+
+    expect(duration).toBeLessThan(5);
+    console.log(`✓ H3 conversion: ${duration.toFixed(2)}ms`);
+  });
+});

package/tests/unit/schema.test.js

@@ -0,0 +1,213 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import HoloSphere from '../../src/index.js';
+
+describe('Unit: Schema Module', () => {
+  let hs;
+
+  beforeEach(() => {
+    hs = new HoloSphere({ relays: [], appName: 'test-schema-unit' });
+  });
+
+  describe('JSON Schema 2019 validation', () => {
+    it('should validate JSON Schema 2019 format', async () => {
+      const schema = {
+        $schema: 'https://json-schema.org/draft/2019-09/schema',
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          value: { type: 'number' }
+        },
+        required: ['id', 'value']
+      };
+
+      // Schema should be valid
+      await expect(
+        hs.setSchema('test', 'test://schema/valid')
+      ).resolves.toBeUndefined();
+    });
+
+    it('should reject invalid schema format', async () => {
+      await expect(
+        hs.setSchema('test', { invalid: 'not a valid schema' })
+      ).rejects.toThrow('ValidationError');
+    });
+
+    it('should support schema type validation', async () => {
+      const holon = await hs.toHolon(37.7749, -122.4194, 9);
+      await hs.setSchema('typed', {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          value: { type: 'number' }
+        },
+        required: ['id', 'value']
+      }, true);
+
+      // Type validation should work in strict mode
+      await expect(
+        hs.write(holon, 'typed', {
+          id: 'test',
+          value: 'not-a-number'  // Should fail if schema requires number
+        }, { strict: true })
+      ).rejects.toThrow('ValidationError');
+    });
+  });
+
+  describe('Ajv validator compilation', () => {
+    it('should compile schema using Ajv', async () => {
+      await hs.setSchema('test', 'test://schema/compile');
+
+      // Schema should be compiled and ready for validation
+      const schema = await hs.getSchema('test');
+      expect(schema).not.toBe(null);
+    });
+
+    it('should reuse compiled validator for same schema', async () => {
+      const holon = await hs.toHolon(37.7749, -122.4194, 9);
+      await hs.setSchema('cached', 'test://schema/cache');
+
+      // Multiple validations should use cached compiled schema
+      await hs.write(holon, 'cached', { id: 'item-1', value: 1 });
+      await hs.write(holon, 'cached', { id: 'item-2', value: 2 });
+      await hs.write(holon, 'cached', { id: 'item-3', value: 3 });
+    });
+  });
+
+  describe('Schema caching (1-hour TTL)', () => {
+    it('should cache schema after first fetch', async () => {
+      await hs.setSchema('cache-test', 'test://schema/ttl');
+
+      const schema1 = await hs.getSchema('cache-test');
+      const schema2 = await hs.getSchema('cache-test');
+
+      // Should return same cached schema
+      expect(schema1).toEqual(schema2);
+    });
+
+    it('should use cached schema for validation', async () => {
+      const holon = await hs.toHolon(37.7749, -122.4194, 9);
+      await hs.setSchema('cached', 'test://schema/cached');
+
+      // First write compiles schema
+      await hs.write(holon, 'cached', { id: 'item-1', value: 1 });
+
+      // Subsequent writes use cached compiled schema
+      await hs.write(holon, 'cached', { id: 'item-2', value: 2 });
+    });
+
+    it('should respect 1-hour cache TTL', async () => {
+      // Note: Actual TTL testing would require mocking time
+      await hs.setSchema('ttl-test', 'test://schema/ttl');
+
+      const schema = await hs.getSchema('ttl-test');
+      expect(schema).not.toBe(null);
+    });
+  });
+
+  describe('Cache expiration and recompilation', () => {
+    it('should allow cache invalidation via clearSchema', async () => {
+      await hs.setSchema('clear-test', 'test://schema/clear');
+
+      const before = await hs.getSchema('clear-test');
+      expect(before).not.toBe(null);
+
+      await hs.clearSchema('clear-test');
+
+      const after = await hs.getSchema('clear-test');
+      expect(after).toBe(null);
+    });
+
+    it('should recompile after cache expiration', async () => {
+      await hs.setSchema('recompile', 'test://schema/recompile');
+
+      // After clearing, should recompile on next use
+      await hs.clearSchema('recompile');
+      await hs.setSchema('recompile', 'test://schema/recompile');
+
+      const schema = await hs.getSchema('recompile');
+      expect(schema).not.toBe(null);
+    });
+  });
+
+  describe('Strict vs permissive mode', () => {
+    it('should allow invalid data in permissive mode', async () => {
+      const holon = await hs.toHolon(37.7749, -122.4194, 9);
+      await hs.setSchema('permissive', 'test://schema/permissive', false);
+
+      // Invalid data should succeed with warning (not thrown)
+      const result = await hs.write(holon, 'permissive', {
+        id: 'invalid',
+        value: 'not-a-number'
+      });
+
+      expect(result).toBe(true);
+    });
+
+    it('should reject invalid data in strict mode', async () => {
+      const holon = await hs.toHolon(37.7749, -122.4194, 9);
+      await hs.setSchema('strict', {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          value: { type: 'number' }
+        },
+        required: ['id', 'value']
+      }, true);
+
+      await expect(
+        hs.write(holon, 'strict', {
+          id: 'invalid',
+          value: 'not-a-number'
+        }, { strict: true })
+      ).rejects.toThrow('ValidationError');
+    });
+
+    it('should log warnings in permissive mode', async () => {
+      const holon = await hs.toHolon(37.7749, -122.4194, 9);
+      await hs.setSchema('log-test', 'test://schema/log', false);
+
+      // Should log warning but not throw
+      const result = await hs.write(holon, 'log-test', {
+        id: 'invalid',
+        invalid: 'field'
+      });
+
+      expect(result).toBe(true);
+    });
+
+    it('should include Ajv errors in ValidationError', async () => {
+      const holon = await hs.toHolon(37.7749, -122.4194, 9);
+      await hs.setSchema('error-test', 'test://schema/error', true);
+
+      try {
+        await hs.write(holon, 'error-test', {
+          id: 'bad',
+          value: 'invalid'
+        }, { strict: true });
+      } catch (err) {
+        expect(err.constructor.name).toBe('ValidationError');
+        expect(err).toHaveProperty('errors');
+        expect(Array.isArray(err.errors)).toBe(true);
+      }
+    });
+  });
+
+  describe('Schema URI handling', () => {
+    it('should fetch schema from URI', async () => {
+      await hs.setSchema('uri-test', 'https://example.com/schema.json');
+      // Should attempt to fetch schema
+    });
+
+    it('should handle schema fetch errors', async () => {
+      // Test that invalid schema objects are rejected
+      await expect(
+        hs.setSchema('fail-test', null)
+      ).rejects.toThrow(Error);
+    });
+
+    it('should support local schema URIs', async () => {
+      await hs.setSchema('local-test', 'file://./schemas/local.json');
+      // Should handle local file URIs
+    });
+  });
+});

package/tests/unit/spatial.test.js

@@ -0,0 +1,158 @@
+import { describe, it, expect } from 'vitest';
+import HoloSphere from '../../src/index.js';
+
+describe('Unit: Spatial Module', () => {
+  const hs = new HoloSphere({ relays: [], appName: 'test-spatial-unit' });
+
+  describe('H3 validation', () => {
+    it('should validate H3 format starts with 8', () => {
+      expect(hs.isValidH3('8928342e20fffff')).toBe(true);
+      expect(hs.isValidH3('7928342e20fffff')).toBe(false);
+    });
+
+    it('should validate H3 format has at least 15 characters', () => {
+      expect(hs.isValidH3('8928342e20fffff')).toBe(true);
+      expect(hs.isValidH3('8928342e20f')).toBe(false);
+      expect(hs.isValidH3('8928342')).toBe(false);
+    });
+
+    it('should validate H3 contains only hex characters', () => {
+      expect(hs.isValidH3('8928342e20fffff')).toBe(true);
+      expect(hs.isValidH3('8928342g20fffff')).toBe(false);
+      expect(hs.isValidH3('8928342!20fffff')).toBe(false);
+    });
+
+    it('should reject non-string inputs', () => {
+      expect(hs.isValidH3(123)).toBe(false);
+      expect(hs.isValidH3(null)).toBe(false);
+      expect(hs.isValidH3(undefined)).toBe(false);
+      expect(hs.isValidH3({})).toBe(false);
+      expect(hs.isValidH3([])).toBe(false);
+    });
+  });
+
+  describe('Coordinate to H3 conversion', () => {
+    it('should convert valid coordinates to H3', async () => {
+      const h3 = await hs.toHolon(37.7749, -122.4194, 9);
+      expect(typeof h3).toBe('string');
+      expect(hs.isValidH3(h3)).toBe(true);
+    });
+
+    it('should produce consistent results for same coordinates', async () => {
+      const h3a = await hs.toHolon(37.7749, -122.4194, 9);
+      const h3b = await hs.toHolon(37.7749, -122.4194, 9);
+      expect(h3a).toBe(h3b);
+    });
+
+    it('should produce different H3 for different resolutions', async () => {
+      const h3res7 = await hs.toHolon(37.7749, -122.4194, 7);
+      const h3res9 = await hs.toHolon(37.7749, -122.4194, 9);
+      expect(h3res7).not.toBe(h3res9);
+    });
+
+    it('should handle resolution 0 (largest)', async () => {
+      const h3 = await hs.toHolon(37.7749, -122.4194, 0);
+      expect(hs.isValidH3(h3)).toBe(true);
+    });
+
+    it('should handle resolution 15 (smallest)', async () => {
+      const h3 = await hs.toHolon(37.7749, -122.4194, 15);
+      expect(hs.isValidH3(h3)).toBe(true);
+    });
+
+    it('should throw RangeError for invalid latitude', async () => {
+      await expect(hs.toHolon(91, -122.4194, 9)).rejects.toThrow(RangeError);
+      await expect(hs.toHolon(-91, -122.4194, 9)).rejects.toThrow(RangeError);
+    });
+
+    it('should throw RangeError for invalid longitude', async () => {
+      await expect(hs.toHolon(37.7749, 181, 9)).rejects.toThrow(RangeError);
+      await expect(hs.toHolon(37.7749, -181, 9)).rejects.toThrow(RangeError);
+    });
+
+    it('should throw RangeError for invalid resolution', async () => {
+      await expect(hs.toHolon(37.7749, -122.4194, -1)).rejects.toThrow(RangeError);
+      await expect(hs.toHolon(37.7749, -122.4194, 16)).rejects.toThrow(RangeError);
+    });
+  });
+
+  describe('Parent/child hierarchy navigation', () => {
+    it('should get parents for valid H3', async () => {
+      const h3 = await hs.toHolon(37.7749, -122.4194, 9);
+      const parents = await hs.getParents(h3);
+      expect(Array.isArray(parents)).toBe(true);
+      expect(parents.length).toBeGreaterThan(0);
+    });
+
+    it('should get parents up to specified maxResolution', async () => {
+      const h3 = await hs.toHolon(37.7749, -122.4194, 9);
+      const parents = await hs.getParents(h3, 5);
+      expect(Array.isArray(parents)).toBe(true);
+      // Should stop at resolution 5
+    });
+
+    it('should return empty array for resolution 0 (no parents)', async () => {
+      const h3 = await hs.toHolon(37.7749, -122.4194, 0);
+      const parents = await hs.getParents(h3);
+      expect(parents).toEqual([]);
+    });
+
+    it('should get 7 children for valid H3', async () => {
+      const h3 = await hs.toHolon(37.7749, -122.4194, 9);
+      const children = await hs.getChildren(h3);
+      expect(Array.isArray(children)).toBe(true);
+      expect(children.length).toBe(7);
+    });
+
+    it('should throw Error for resolution 15 (no children)', async () => {
+      const h3 = await hs.toHolon(37.7749, -122.4194, 15);
+      await expect(hs.getChildren(h3)).rejects.toThrow(Error);
+    });
+
+    it('should validate parent-child relationships', async () => {
+      const parent = await hs.toHolon(37.7749, -122.4194, 7);
+      const children = await hs.getChildren(parent);
+
+      // One of the children should contain our test point at resolution 8
+      expect(children.length).toBe(7);
+    });
+  });
+
+  describe('Resolution extraction', () => {
+    it('should extract resolution from H3 ID', async () => {
+      const h3res5 = await hs.toHolon(37.7749, -122.4194, 5);
+      const h3res9 = await hs.toHolon(37.7749, -122.4194, 9);
+      const h3res12 = await hs.toHolon(37.7749, -122.4194, 12);
+
+      // getResolution should be available if implemented
+      if (typeof hs.getResolution === 'function') {
+        expect(hs.getResolution(h3res5)).toBe(5);
+        expect(hs.getResolution(h3res9)).toBe(9);
+        expect(hs.getResolution(h3res12)).toBe(12);
+      }
+    });
+  });
+
+  describe('Edge cases', () => {
+    it('should handle coordinates at poles', async () => {
+      const northPole = await hs.toHolon(89.9, 0, 5);
+      const southPole = await hs.toHolon(-89.9, 0, 5);
+
+      expect(hs.isValidH3(northPole)).toBe(true);
+      expect(hs.isValidH3(southPole)).toBe(true);
+    });
+
+    it('should handle coordinates at dateline', async () => {
+      const east = await hs.toHolon(0, 179.9, 5);
+      const west = await hs.toHolon(0, -179.9, 5);
+
+      expect(hs.isValidH3(east)).toBe(true);
+      expect(hs.isValidH3(west)).toBe(true);
+    });
+
+    it('should handle coordinates at equator and prime meridian', async () => {
+      const origin = await hs.toHolon(0, 0, 9);
+      expect(hs.isValidH3(origin)).toBe(true);
+    });
+  });
+});

package/tests/unit/storage.test.js

@@ -0,0 +1,195 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import HoloSphere from '../../src/index.js';
+
+describe('Unit: Storage Module', () => {
+  let hs;
+  let testHolonId;
+
+  beforeEach(async () => {
+    hs = new HoloSphere({ relays: [], appName: 'test-storage-unit' });
+    testHolonId = await hs.toHolon(37.7749, -122.4194, 9);
+  });
+
+  describe('Path construction', () => {
+    it('should construct path with appname/holon/lens/key format', async () => {
+      // Internal path construction (implementation detail)
+      // Path should follow format: appname/holon/lens/key
+      await hs.write(testHolonId, 'test-lens', { id: 'test-key', data: 'value' });
+
+      const result = await hs.read(testHolonId, 'test-lens', 'test-key');
+      expect(result).not.toBe(null);
+    });
+
+    it('should encode special characters in paths', async () => {
+      const lensWithSpaces = 'my test lens';
+      const keyWithSpecial = 'key!@#$%';
+
+      await hs.write(testHolonId, lensWithSpaces, {
+        id: keyWithSpecial,
+        data: 'test'
+      });
+
+      const result = await hs.read(testHolonId, lensWithSpaces, keyWithSpecial);
+      expect(result).not.toBe(null);
+    });
+
+    it('should handle unicode characters in paths', async () => {
+      const unicodeLens = '测试镜头';
+      const unicodeKey = 'キー001';
+
+      await hs.write(testHolonId, unicodeLens, {
+        id: unicodeKey,
+        data: 'unicode test'
+      });
+
+      const result = await hs.read(testHolonId, unicodeLens, unicodeKey);
+      expect(result).not.toBe(null);
+    });
+  });
+
+  describe('Gun graph operations', () => {
+    it('should perform Gun .put() for write', async () => {
+      const success = await hs.write(testHolonId, 'test', {
+        id: 'item-1',
+        value: 'data'
+      });
+
+      expect(success).toBe(true);
+    });
+
+    it('should perform Gun .once() for read', async () => {
+      await hs.write(testHolonId, 'test', { id: 'item-1', value: 'data' });
+
+      const result = await hs.read(testHolonId, 'test', 'item-1');
+      expect(result).toMatchObject({ id: 'item-1', value: 'data' });
+    });
+
+    it('should return null for non-existent data', async () => {
+      const result = await hs.read(testHolonId, 'nonexistent', 'nonexistent');
+      expect(result).toBe(null);
+    });
+
+    it('should perform Gun .put(null) for delete (tombstone)', async () => {
+      await hs.write(testHolonId, 'test', { id: 'item-1', value: 'data' });
+
+      const deleted = await hs.delete(testHolonId, 'test', 'item-1');
+      expect(deleted).toBe(true);
+
+      const result = await hs.read(testHolonId, 'test', 'item-1');
+      expect(result).toBe(null);
+    });
+
+    it('should perform Gun .on() for subscribe', () => {
+      const callback = () => {};
+      const subscription = hs.subscribe(testHolonId, 'test', callback);
+
+      expect(subscription).toHaveProperty('unsubscribe');
+      subscription.unsubscribe();
+    });
+  });
+
+  describe('Radisk persistence', () => {
+    it('should persist data with radisk enabled', async () => {
+      const hsWithRadisk = new HoloSphere({
+        appName: 'radisk-test',
+        radisk: true
+      });
+
+      const holon = await hsWithRadisk.toHolon(37.7749, -122.4194, 9);
+      await hsWithRadisk.write(holon, 'persist', {
+        id: 'persist-1',
+        value: 'persisted'
+      });
+
+      // Data should be written to disk via radisk
+      const result = await hsWithRadisk.read(holon, 'persist', 'persist-1');
+      expect(result).not.toBe(null);
+    });
+
+    it('should work without radisk when disabled', async () => {
+      const hsNoRadisk = new HoloSphere({
+        appName: 'no-radisk-test',
+        radisk: false
+      });
+
+      const holon = await hsNoRadisk.toHolon(37.7749, -122.4194, 9);
+      await hsNoRadisk.write(holon, 'memory', {
+        id: 'mem-1',
+        value: 'in-memory'
+      });
+
+      const result = await hsNoRadisk.read(holon, 'memory', 'mem-1');
+      expect(result).not.toBe(null);
+    });
+  });
+
+  describe('Path encoding', () => {
+    it('should encode forward slashes in lens names', async () => {
+      const lensWithSlash = 'category/subcategory';
+      await hs.write(testHolonId, lensWithSlash, {
+        id: 'item-1',
+        data: 'test'
+      });
+
+      const result = await hs.read(testHolonId, lensWithSlash, 'item-1');
+      expect(result).not.toBe(null);
+    });
+
+    it('should encode dots in keys', async () => {
+      await hs.write(testHolonId, 'test', {
+        id: 'item.with.dots',
+        data: 'test'
+      });
+
+      const result = await hs.read(testHolonId, 'test', 'item.with.dots');
+      expect(result).not.toBe(null);
+    });
+
+    it('should handle empty strings gracefully', async () => {
+      await expect(
+        hs.write(testHolonId, '', { id: 'test' })
+      ).rejects.toThrow(Error);
+    });
+  });
+
+  describe('Error handling', () => {
+    it('should handle Gun connection errors', async () => {
+      // Test with invalid configuration
+      const hsInvalid = new HoloSphere({
+        appName: 'invalid-test',
+        peers: ['https://nonexistent.invalid/gun']
+      });
+
+      // Should still work locally with radisk
+      const holon = await hsInvalid.toHolon(37.7749, -122.4194, 9);
+      const success = await hsInvalid.write(holon, 'test', {
+        id: 'test-1',
+        data: 'local'
+      });
+
+      // May succeed locally even if peer connection fails
+      expect(typeof success).toBe('boolean');
+    });
+
+    it('should handle malformed data gracefully', async () => {
+      // Gun should handle various data types
+      await hs.write(testHolonId, 'test', {
+        id: 'complex',
+        nested: { deep: { object: 'value' } },
+        array: [1, 2, 3],
+        number: 42,
+        boolean: true
+      });
+
+      const result = await hs.read(testHolonId, 'test', 'complex');
+      expect(result).not.toBe(null);
+    });
+
+    it('should throw ValidationError on invalid input', async () => {
+      // Should throw ValidationError with empty holon ID
+      await expect(
+        hs.write('', 'test', { id: 'test' })
+      ).rejects.toThrow('holonId must be a non-empty string');
+    });
+  });
+});