holosphere 1.1.20 → 2.0.0-alpha0

package/src/schema/validator.js

@@ -0,0 +1,91 @@
+/**
+ * JSON Schema Validation with Ajv and caching
+ */
+
+import Ajv from 'ajv';
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+const schemaCache = new Map();
+const CACHE_TTL = 3600000; // 1 hour in milliseconds
+
+/**
+ * Validation Error class
+ */
+export class ValidationError extends Error {
+  constructor(message, errors = []) {
+    super(message);
+    this.name = 'ValidationError';
+    this.errors = errors;
+  }
+}
+
+/**
+ * Compile and cache JSON Schema
+ * @param {Object} schema - JSON Schema object
+ * @param {string} lensName - Lens identifier for caching
+ * @returns {Function} Ajv validator function
+ */
+export function compileSchema(schema, lensName) {
+  const cacheKey = lensName;
+  const cached = schemaCache.get(cacheKey);
+
+  // Check if cached and not expired
+  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+    return cached.validator;
+  }
+
+  // Compile new validator
+  try {
+    const validator = ajv.compile(schema);
+    schemaCache.set(cacheKey, {
+      validator,
+      timestamp: Date.now(),
+    });
+    return validator;
+  } catch (error) {
+    throw new Error(`Schema compilation failed: ${error.message}`);
+  }
+}
+
+/**
+ * Validate data against schema
+ * @param {Object} data - Data to validate
+ * @param {Object} schema - JSON Schema object
+ * @param {string} lensName - Lens name for caching
+ * @param {boolean} strict - Throw error if invalid (default: false)
+ * @returns {boolean} True if valid
+ * @throws {ValidationError} If strict=true and validation fails
+ */
+export function validate(data, schema, lensName, strict = false) {
+  const validator = compileSchema(schema, lensName);
+  const valid = validator(data);
+
+  if (!valid) {
+    const errors = validator.errors || [];
+    const errorMessage = errors.map((e) => `${e.instancePath} ${e.message}`).join('; ');
+
+    if (strict) {
+      throw new ValidationError(`ValidationError: Validation failed: ${errorMessage}`, errors);
+    } else {
+      console.warn(`[Schema Validation Warning] ${lensName}: ${errorMessage}`);
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Clear schema cache for a lens
+ * @param {string} lensName - Lens name
+ */
+export function clearSchemaCache(lensName) {
+  schemaCache.delete(lensName);
+}
+
+/**
+ * Clear all cached schemas
+ */
+export function clearAllCaches() {
+  schemaCache.clear();
+}

package/src/spatial/h3-operations.js

@@ -0,0 +1,110 @@
+import {
+  latLngToCell,
+  cellToParent,
+  cellToChildren,
+  isValidCell,
+  getResolution,
+} from 'h3-js';
+
+/**
+ * Convert geographic coordinates to H3 holon ID
+ * @param {number} lat - Latitude (-90 to 90)
+ * @param {number} lng - Longitude (-180 to 180)
+ * @param {number} resolution - H3 resolution (0-15)
+ * @returns {string} H3 cell ID
+ */
+export function toHolon(lat, lng, resolution) {
+  // Validate inputs
+  if (typeof lat !== 'number' || lat < -90 || lat > 90) {
+    throw new RangeError(`Invalid latitude: ${lat}. Must be between -90 and 90.`);
+  }
+  if (typeof lng !== 'number' || lng < -180 || lng > 180) {
+    throw new RangeError(`Invalid longitude: ${lng}. Must be between -180 and 180.`);
+  }
+  if (!Number.isInteger(resolution) || resolution < 0 || resolution > 15) {
+    throw new RangeError(`Invalid resolution: ${resolution}. Must be integer between 0 and 15.`);
+  }
+
+  try {
+    const h3Index = latLngToCell(lat, lng, resolution);
+    return h3Index;
+  } catch (error) {
+    throw new Error(`H3 conversion failed: ${error.message}`);
+  }
+}
+
+/**
+ * Get all parent holons up the hierarchy
+ * @param {string} holonId - H3 cell ID
+ * @param {number} maxResolution - Stop at this resolution (default: 0)
+ * @returns {string[]} Array of parent H3 IDs (ascending hierarchy)
+ */
+export function getParents(holonId, maxResolution = 0) {
+  if (!isValidH3(holonId)) {
+    throw new Error(`Invalid H3 holon ID: ${holonId}`);
+  }
+
+  const currentResolution = getResolution(holonId);
+  const parents = [];
+
+  let currentCell = holonId;
+  for (let res = currentResolution - 1; res >= maxResolution; res--) {
+    try {
+      currentCell = cellToParent(currentCell, res);
+      parents.push(currentCell);
+    } catch (error) {
+      break; // Reached root
+    }
+  }
+
+  return parents;
+}
+
+/**
+ * Get all child holons at next resolution level
+ * @param {string} holonId - H3 cell ID
+ * @returns {string[]} Array of child H3 IDs (7 children per hexagon)
+ */
+export function getChildren(holonId) {
+  if (!isValidH3(holonId)) {
+    throw new Error(`Invalid H3 holon ID: ${holonId}`);
+  }
+
+  try {
+    const resolution = getResolution(holonId);
+    // H3 max resolution is 15, can't get children of resolution 15
+    if (resolution >= 15) {
+      throw new Error('Cannot get children of resolution 15 cell (maximum resolution)');
+    }
+
+    // cellToChildren requires the child resolution (one level down)
+    const children = cellToChildren(holonId, resolution + 1);
+    return children;
+  } catch (error) {
+    throw new Error(`Failed to get children: ${error.message}`);
+  }
+}
+
+/**
+ * Validate H3 cell ID format
+ * @param {string} holonId - H3 cell ID
+ * @returns {boolean} True if valid H3 format
+ */
+export function isValidH3(holonId) {
+  if (typeof holonId !== 'string') return false;
+  if (holonId.length < 15) return false;
+  if (!holonId.startsWith('8')) return false;
+  return isValidCell(holonId);
+}
+
+/**
+ * Get H3 resolution level from cell ID
+ * @param {string} holonId - H3 cell ID
+ * @returns {number} Resolution (0-15)
+ */
+export function getH3Resolution(holonId) {
+  if (!isValidH3(holonId)) {
+    throw new Error(`Invalid H3 holon ID: ${holonId}`);
+  }
+  return getResolution(holonId);
+}

package/src/storage/backend-factory.js

@@ -0,0 +1,125 @@
+/**
+ * Factory for creating storage backends
+ * Supports lazy loading of backend implementations
+ */
+
+const BACKEND_MODULES = {
+  nostr: './backends/nostr-backend.js',
+  gundb: './backends/gundb-backend.js',
+  activitypub: './backends/activitypub-backend.js',
+};
+
+// Cache for loaded backend classes
+const loadedBackends = new Map();
+
+/**
+ * Factory for creating storage backends
+ */
+export class BackendFactory {
+  /**
+   * Get list of available backend types
+   * @returns {string[]} Available backend type names
+   */
+  static getAvailableBackends() {
+    return Object.keys(BACKEND_MODULES);
+  }
+
+  /**
+   * Check if a backend type is available
+   * @param {string} type - Backend type
+   * @returns {boolean} Whether the backend is available
+   */
+  static isAvailable(type) {
+    return type in BACKEND_MODULES;
+  }
+
+  /**
+   * Load a backend class dynamically
+   * @param {string} type - Backend type
+   * @returns {Promise<Class>} Backend class
+   */
+  static async loadBackend(type) {
+    if (loadedBackends.has(type)) {
+      return loadedBackends.get(type);
+    }
+
+    const modulePath = BACKEND_MODULES[type];
+    if (!modulePath) {
+      throw new Error(
+        `Unknown backend type: '${type}'. Available backends: ${Object.keys(BACKEND_MODULES).join(', ')}`
+      );
+    }
+
+    try {
+      const module = await import(modulePath);
+      const BackendClass = module.default || module[`${capitalize(type)}Backend`];
+
+      if (!BackendClass) {
+        throw new Error(`Backend module '${type}' does not export a valid backend class`);
+      }
+
+      loadedBackends.set(type, BackendClass);
+      return BackendClass;
+    } catch (error) {
+      if (error.code === 'ERR_MODULE_NOT_FOUND') {
+        throw new Error(
+          `Backend '${type}' requires additional dependencies. ` +
+          `Please install them: ${getDependencyHint(type)}`
+        );
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Create a storage backend instance
+   * @param {string} type - Backend type: 'nostr' | 'gundb' | 'activitypub'
+   * @param {Object} config - Backend-specific configuration
+   * @returns {Promise<StorageBackend>} Initialized backend
+   */
+  static async create(type, config) {
+    const BackendClass = await this.loadBackend(type);
+    const backend = new BackendClass(config);
+    await backend.init();
+    return backend;
+  }
+
+  /**
+   * Register a custom backend
+   * @param {string} name - Backend name
+   * @param {Class|string} BackendClassOrPath - Backend class or module path
+   */
+  static register(name, BackendClassOrPath) {
+    if (typeof BackendClassOrPath === 'string') {
+      BACKEND_MODULES[name] = BackendClassOrPath;
+    } else {
+      loadedBackends.set(name, BackendClassOrPath);
+      BACKEND_MODULES[name] = null; // Mark as registered but not file-based
+    }
+  }
+}
+
+/**
+ * Capitalize first letter
+ * @param {string} str - String to capitalize
+ * @returns {string} Capitalized string
+ */
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Get dependency installation hint for a backend
+ * @param {string} type - Backend type
+ * @returns {string} Installation hint
+ */
+function getDependencyHint(type) {
+  const hints = {
+    nostr: 'npm install nostr-tools',
+    gundb: 'npm install gun',
+    activitypub: 'npm install express',
+  };
+  return hints[type] || 'Check the documentation for required dependencies';
+}
+
+export default BackendFactory;

package/src/storage/backend-interface.js

@@ -0,0 +1,142 @@
+/**
+ * Abstract Storage Backend Interface
+ * All storage backends must implement this interface
+ */
+export class StorageBackend {
+  constructor(config) {
+    if (new.target === StorageBackend) {
+      throw new Error('StorageBackend is abstract and cannot be instantiated directly');
+    }
+    this.config = config;
+    this.publicKey = null;
+  }
+
+  /**
+   * Initialize the backend
+   * @returns {Promise<void>}
+   */
+  async init() {
+    throw new Error('init() must be implemented by subclass');
+  }
+
+  /**
+   * Build path from components
+   * @param {string} appName - Application namespace
+   * @param {string} holonId - Holon identifier (H3 hex or URI)
+   * @param {string} lensName - Lens name
+   * @param {string} [key] - Optional data key
+   * @returns {string} Constructed path
+   */
+  buildPath(appName, holonId, lensName, key = null) {
+    throw new Error('buildPath() must be implemented by subclass');
+  }
+
+  /**
+   * Write data to storage
+   * @param {string} path - Storage path
+   * @param {Object} data - Data to write
+   * @param {Object} [options] - Write options
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async write(path, data, options = {}) {
+    throw new Error('write() must be implemented by subclass');
+  }
+
+  /**
+   * Read data from storage
+   * @param {string} path - Storage path
+   * @param {Object} [options] - Read options
+   * @param {string[]} [options.authors] - Public keys to query
+   * @param {boolean} [options.includeAuthor] - Include author in response
+   * @returns {Promise<Object|null>} Data or null
+   */
+  async read(path, options = {}) {
+    throw new Error('read() must be implemented by subclass');
+  }
+
+  /**
+   * Read all data under a path prefix
+   * @param {string} path - Path prefix
+   * @param {Object} [options] - Query options
+   * @param {boolean} [options.hybrid] - Use hybrid mode (local + remote)
+   * @param {string[]} [options.authors] - Public keys to query
+   * @returns {Promise<Object[]>} Array of data objects
+   */
+  async readAll(path, options = {}) {
+    throw new Error('readAll() must be implemented by subclass');
+  }
+
+  /**
+   * Update data (merge fields)
+   * @param {string} path - Storage path
+   * @param {Object} updates - Fields to update
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async update(path, updates) {
+    throw new Error('update() must be implemented by subclass');
+  }
+
+  /**
+   * Delete data at path
+   * @param {string} path - Storage path
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async delete(path) {
+    throw new Error('delete() must be implemented by subclass');
+  }
+
+  /**
+   * Delete all data under path prefix
+   * @param {string} path - Path prefix
+   * @returns {Promise<Object>} Deletion results { success: boolean, count: number }
+   */
+  async deleteAll(path) {
+    throw new Error('deleteAll() must be implemented by subclass');
+  }
+
+  /**
+   * Subscribe to data changes
+   * @param {string} path - Path or path prefix
+   * @param {Function} callback - Called on changes: (data, key) => void
+   * @param {Object} [options] - Subscription options
+   * @returns {Promise<Object>} Subscription with unsubscribe() method
+   */
+  async subscribe(path, callback, options = {}) {
+    throw new Error('subscribe() must be implemented by subclass');
+  }
+
+  /**
+   * Export all data for migration
+   * @param {string} [pathPrefix] - Optional prefix to filter
+   * @returns {Promise<Object[]>} Array of exportable records
+   */
+  async exportData(pathPrefix = '') {
+    throw new Error('exportData() must be implemented by subclass');
+  }
+
+  /**
+   * Import data from migration
+   * @param {Object[]} records - Records to import
+   * @param {Object} [options] - Import options
+   * @param {boolean} [options.overwrite] - Overwrite existing data
+   * @returns {Promise<Object>} Import results { success: number, failed: number, errors: [] }
+   */
+  async importData(records, options = {}) {
+    throw new Error('importData() must be implemented by subclass');
+  }
+
+  /**
+   * Close connections and cleanup
+   */
+  close() {
+    throw new Error('close() must be implemented by subclass');
+  }
+
+  /**
+   * Get backend status/health
+   * @returns {Object} Status information { type, publicKey, connected, ... }
+   */
+  getStatus() {
+    throw new Error('getStatus() must be implemented by subclass');
+  }
+}