holosphere 1.1.20 → 2.0.0-alpha1

package/src/storage/filesystem-storage.js

@@ -0,0 +1,138 @@
+/**
+ * File system storage adapter for Node.js
+ * Stores events as JSON files in a directory structure
+ * This module is only loaded in Node.js environments
+ */
+
+// Guard against browser environments
+if (typeof window !== 'undefined') {
+  throw new Error('FileSystemStorage is not available in browser environments');
+}
+
+import { PersistentStorage } from './persistent-storage.js';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+
+export class FileSystemStorage extends PersistentStorage {
+  constructor(baseDir = null) {
+    super();
+    this.baseDir = baseDir || path.join(os.homedir(), '.holosphere');
+    this.namespace = null;
+    this.storageDir = null;
+  }
+
+  async init(namespace) {
+    this.namespace = namespace;
+    this.storageDir = path.join(this.baseDir, namespace);
+
+    // Create directory if it doesn't exist
+    try {
+      await fs.mkdir(this.storageDir, { recursive: true });
+    } catch (error) {
+      if (error.code !== 'EEXIST') {
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * Convert key to safe filename
+   * @private
+   */
+  _keyToFilename(key) {
+    // Replace unsafe characters
+    return key.replace(/[^a-zA-Z0-9-_]/g, '_') + '.json';
+  }
+
+  /**
+   * Get full file path for key
+   * @private
+   */
+  _getFilePath(key) {
+    return path.join(this.storageDir, this._keyToFilename(key));
+  }
+
+  async put(key, event) {
+    const filePath = this._getFilePath(key);
+    const data = JSON.stringify(event, null, 2);
+    await fs.writeFile(filePath, data, 'utf8');
+  }
+
+  async get(key) {
+    const filePath = this._getFilePath(key);
+    try {
+      const data = await fs.readFile(filePath, 'utf8');
+      return JSON.parse(data);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return null; // File doesn't exist
+      }
+      throw error;
+    }
+  }
+
+  async getAll(prefix) {
+    const results = [];
+
+    try {
+      const files = await fs.readdir(this.storageDir);
+
+      for (const file of files) {
+        if (!file.endsWith('.json')) continue;
+
+        const filePath = path.join(this.storageDir, file);
+        try {
+          const data = await fs.readFile(filePath, 'utf8');
+          const event = JSON.parse(data);
+
+          // Check if this event matches the prefix
+          // The key is stored in the event's d-tag or we derive it from filename
+          const dTag = event.tags?.find(t => t[0] === 'd');
+          const key = dTag ? dTag[1] : file.replace('.json', '').replace(/_/g, '/');
+
+          if (key.startsWith(prefix)) {
+            results.push(event);
+          }
+        } catch (error) {
+          // Skip files that can't be read or parsed (silently)
+          // This is common for outbox queue entries and other non-event files
+        }
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+
+    return results;
+  }
+
+  async delete(key) {
+    const filePath = this._getFilePath(key);
+    try {
+      await fs.unlink(filePath);
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+  }
+
+  async clear() {
+    try {
+      const files = await fs.readdir(this.storageDir);
+      await Promise.all(
+        files.map(file => fs.unlink(path.join(this.storageDir, file)))
+      );
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+  }
+
+  async close() {
+    // Nothing to close for file system storage
+  }
+}

package/src/storage/global-tables.js

@@ -0,0 +1,81 @@
+/**
+ * Global Data Operations
+ * Non-location-specific storage (FR-044, FR-045)
+ */
+
+import { write, read, readAll, update, deleteData, deleteAll } from './nostr-wrapper.js';
+
+/**
+ * Write data to global table
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} table - Global table name
+ * @param {Object} data - Data to write (must contain id field)
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function writeGlobal(client, appname, table, data) {
+  // Auto-generate ID if not provided
+  if (!data.id) {
+    data.id = `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  const path = `${appname}/${table}/${data.id}`;
+  return write(client, path, data);
+}
+
+/**
+ * Read data from global table
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} table - Global table name
+ * @param {string} key - Data key (optional, if not provided returns all)
+ * @returns {Promise<Object|Object[]|null>} Data or null
+ */
+export async function readGlobal(client, appname, table, key = null) {
+  if (key) {
+    const path = `${appname}/${table}/${key}`;
+    return read(client, path);
+  } else {
+    const path = `${appname}/${table}`;
+    return readAll(client, path);
+  }
+}
+
+/**
+ * Update data in global table
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} table - Global table name
+ * @param {string} key - Data key
+ * @param {Object} updates - Fields to update
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function updateGlobal(client, appname, table, key, updates) {
+  const path = `${appname}/${table}/${key}`;
+  return update(client, path, updates);
+}
+
+/**
+ * Delete data from global table
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} table - Global table name
+ * @param {string} key - Data key
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function deleteGlobal(client, appname, table, key) {
+  const path = `${appname}/${table}/${key}`;
+  return deleteData(client, path);
+}
+
+/**
+ * Delete all data from global table
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} table - Global table name
+ * @returns {Promise<Object>} Deletion results
+ */
+export async function deleteAllGlobal(client, appname, table) {
+  const path = `${appname}/${table}`;
+  return deleteAll(client, path);
+}

package/src/storage/gun-async.js

@@ -0,0 +1,281 @@
+/**
+ * Gun Async Utilities
+ * Provides Promise-based wrappers and async patterns for Gun operations
+ */
+
+/**
+ * Get data from Gun using native .then() support
+ * @param {Object} gunChain - Gun chain reference
+ * @param {number} timeout - Timeout in ms (default 1000ms)
+ * @returns {Promise<any>} Promise resolving to data
+ */
+export function gunPromise(gunChain, timeout = 1000) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        resolve(null);
+      }
+    }, timeout);
+
+    gunChain.once((data) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve(data || null);
+      }
+    });
+  });
+}
+
+/**
+ * Wait for Gun write acknowledgement
+ * @param {Object} gunChain - Gun chain reference
+ * @param {any} data - Data to write
+ * @param {number} timeout - Timeout in ms (default 1000ms)
+ * @returns {Promise<Object>} Promise resolving to ack object
+ */
+export function gunPut(gunChain, data, timeout = 1000) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        resolve({ ok: true, timeout: true });
+      }
+    }, timeout);
+
+    gunChain.put(data, (ack) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        if (ack.err) {
+          reject(new Error(ack.err));
+        } else {
+          resolve(ack);
+        }
+      }
+    });
+  });
+}
+
+/**
+ * Get all items from a Gun map
+ * @param {Object} gunChain - Gun chain reference
+ * @param {number} timeout - Timeout in ms (default 300ms)
+ * @returns {Promise<Object>} Promise resolving to map of items
+ */
+export async function gunMap(gunChain, timeout = 300) {
+  return new Promise((resolve) => {
+    const items = {};
+
+    gunChain.map().once((data, key) => {
+      if (data && !key.startsWith('_')) {
+        items[key] = data;
+      }
+    });
+
+    setTimeout(() => {
+      resolve(items);
+    }, timeout);
+  });
+}
+
+/**
+ * Load full chain data (follows all references)
+ * @param {Object} gunChain - Gun chain reference
+ * @param {number} depth - Max depth to traverse (default 3)
+ * @returns {Promise<any>} Promise resolving to loaded data
+ */
+export async function gunLoad(gunChain, depth = 3) {
+  return new Promise((resolve) => {
+    let result = null;
+
+    gunChain.load((data) => {
+      result = data;
+    }, { wait: 100 });
+
+    setTimeout(() => {
+      resolve(result);
+    }, 100 * depth);
+  });
+}
+
+/**
+ * Async iterator for Gun map
+ * @param {Object} gunChain - Gun chain reference
+ * @returns {AsyncGenerator} Async generator yielding [key, value] pairs
+ */
+export async function* gunMapIterator(gunChain) {
+  const items = await gunMap(gunChain);
+  for (const [key, value] of Object.entries(items)) {
+    yield [key, value];
+  }
+}
+
+/**
+ * Collect Gun on() stream into array over time
+ * @param {Object} gunChain - Gun chain reference
+ * @param {number} duration - Collection duration in ms
+ * @returns {Promise<Array>} Promise resolving to array of data
+ */
+export async function gunCollect(gunChain, duration = 500) {
+  return new Promise((resolve) => {
+    const results = [];
+    const seen = new Set();
+
+    const listener = gunChain.on((data, key) => {
+      if (data && !seen.has(key)) {
+        seen.add(key);
+        results.push({ key, data });
+      }
+    });
+
+    setTimeout(() => {
+      listener.off();
+      resolve(results);
+    }, duration);
+  });
+}
+
+/**
+ * Wait for specific condition on Gun data
+ * @param {Object} gunChain - Gun chain reference
+ * @param {Function} predicate - Condition function (data) => boolean
+ * @param {number} timeout - Timeout in ms (default 5000ms)
+ * @returns {Promise<any>} Promise resolving when condition is met
+ */
+export async function gunWaitFor(gunChain, predicate, timeout = 5000) {
+  return new Promise((resolve, reject) => {
+    let timeoutId;
+    let listener;
+
+    const cleanup = () => {
+      if (timeoutId) clearTimeout(timeoutId);
+      if (listener) listener.off();
+    };
+
+    listener = gunChain.on((data) => {
+      if (predicate(data)) {
+        cleanup();
+        resolve(data);
+      }
+    });
+
+    timeoutId = setTimeout(() => {
+      cleanup();
+      reject(new Error('Timeout waiting for condition'));
+    }, timeout);
+  });
+}
+
+/**
+ * Batch read multiple Gun paths
+ * @param {Object} gun - Gun instance
+ * @param {string[]} paths - Array of paths to read
+ * @returns {Promise<Object>} Object mapping paths to data
+ */
+export async function gunBatchGet(gun, paths) {
+  const promises = paths.map(async (path) => {
+    const data = await gunPromise(gun.get(path));
+    return [path, data];
+  });
+
+  const results = await Promise.all(promises);
+  return Object.fromEntries(results);
+}
+
+/**
+ * Batch write multiple Gun paths
+ * @param {Object} gun - Gun instance
+ * @param {Object} pathDataMap - Object mapping paths to data
+ * @returns {Promise<Object>} Object mapping paths to ack results
+ */
+export async function gunBatchPut(gun, pathDataMap) {
+  const promises = Object.entries(pathDataMap).map(async ([path, data]) => {
+    const ack = await gunPut(gun.get(path), data);
+    return [path, ack];
+  });
+
+  const results = await Promise.all(promises);
+  return Object.fromEntries(results);
+}
+
+/**
+ * Retry Gun operation with exponential backoff
+ * @param {Function} operation - Async function to retry
+ * @param {number} maxRetries - Max retry attempts (default 3)
+ * @param {number} baseDelay - Base delay in ms (default 100ms)
+ * @returns {Promise<any>} Promise resolving to operation result
+ */
+export async function gunRetry(operation, maxRetries = 3, baseDelay = 100) {
+  let lastError;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      if (attempt < maxRetries) {
+        const delay = baseDelay * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Create async stream from Gun on() callback
+ * @param {Object} gunChain - Gun chain reference
+ * @returns {Object} Stream object with async iteration support
+ */
+export function gunStream(gunChain) {
+  let listeners = [];
+  let buffer = [];
+  let ended = false;
+
+  const stream = {
+    [Symbol.asyncIterator]() {
+      return {
+        async next() {
+          if (buffer.length > 0) {
+            return { value: buffer.shift(), done: false };
+          }
+
+          if (ended) {
+            return { done: true };
+          }
+
+          // Wait for next value
+          return new Promise((resolve) => {
+            listeners.push((data) => {
+              resolve({ value: data, done: false });
+            });
+          });
+        },
+      };
+    },
+
+    stop() {
+      ended = true;
+      if (this.listener) this.listener.off();
+    },
+  };
+
+  stream.listener = gunChain.on((data, key) => {
+    const item = { key, data };
+    if (listeners.length > 0) {
+      const listener = listeners.shift();
+      listener(item);
+    } else {
+      buffer.push(item);
+    }
+  });
+
+  return stream;
+}

package/src/storage/gun-wrapper.js

@@ -0,0 +1,221 @@
+/**
+ * GunDB Storage Wrapper with radisk persistence
+ * Handles path construction and CRUD operations
+ */
+
+import { gunPromise, gunPut, gunCollect } from './gun-async.js';
+
+/**
+ * Build Gun path from components
+ * @param {string} appname - Application namespace
+ * @param {string} holon - Holon ID (H3 or URI)
+ * @param {string} lens - Lens name
+ * @param {string} key - Data key (optional)
+ * @returns {string} Gun path
+ */
+export function buildPath(appname, holon, lens, key = null) {
+  // Encode components to handle special characters
+  const encodedHolon = encodePathComponent(holon);
+  const encodedLens = encodePathComponent(lens);
+
+  if (key) {
+    const encodedKey = encodePathComponent(key);
+    return `${appname}/${encodedHolon}/${encodedLens}/${encodedKey}`;
+  }
+  return `${appname}/${encodedHolon}/${encodedLens}`;
+}
+
+/**
+ * Encode path component to handle special characters
+ * @private
+ */
+function encodePathComponent(component) {
+  return encodeURIComponent(component).replace(/%2F/g, '/');
+}
+
+/**
+ * Write data to Gun with radisk persistence
+ * @param {Object} gun - Gun instance
+ * @param {string} path - Gun path
+ * @param {Object} data - Data to write
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function write(gun, path, data) {
+  try {
+    await gunPut(gun.get(path), data, 2000);
+    // Delay to allow Gun to propagate the write (50ms for better reliability)
+    await new Promise(resolve => setTimeout(resolve, 50));
+    return true;
+  } catch (error) {
+    throw error;
+  }
+}
+
+/**
+ * Read data from Gun
+ * @param {Object} gun - Gun instance
+ * @param {string} path - Gun path
+ * @returns {Promise<Object|null>} Data or null if not found
+ */
+export async function read(gun, path) {
+  const data = await gunPromise(gun.get(path), 2000);
+
+  // Return null if deleted or not found
+  if (!data || data._deleted) {
+    return null;
+  }
+
+  return data;
+}
+
+/**
+ * Read all data under a path (lens query)
+ * @param {Object} gun - Gun instance
+ * @param {string} path - Gun path
+ * @returns {Promise<Object[]>} Array of data objects
+ */
+export async function readAll(gun, path) {
+  const results = await gunCollect(gun.get(path), 1000);
+
+  // Filter out deleted items and Gun metadata
+  return results
+    .filter(({ data, key }) => {
+      if (!data || typeof data !== 'object') return false;
+      if (key.startsWith('_')) return false;
+      if (data._deleted) return false;
+      return true;
+    })
+    .map(({ data }) => data);
+}
+
+/**
+ * Update data (merge fields)
+ * @param {Object} gun - Gun instance
+ * @param {string} path - Gun path
+ * @param {Object} updates - Fields to update
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function update(gun, path, updates) {
+  const existing = await gunPromise(gun.get(path));
+
+  if (!existing || !existing.id || existing._deleted) {
+    return false; // Not found or deleted
+  }
+
+  // Remove Gun metadata before merging
+  const cleanExisting = { ...existing };
+  delete cleanExisting['_'];
+
+  // Merge updates
+  const merged = { ...cleanExisting, ...updates };
+
+  try {
+    await gunPut(gun.get(path), merged);
+    return true;
+  } catch (error) {
+    throw error;
+  }
+}
+
+/**
+ * Delete data (tombstone)
+ * @param {Object} gun - Gun instance
+ * @param {string} path - Gun path
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function deleteData(gun, path) {
+  try {
+    // Gun requires tombstone to be an object with _deleted flag
+    // First read existing data to preserve metadata
+    const existing = await gunPromise(gun.get(path));
+    if (!existing) {
+      return true; // Already deleted/doesn't exist
+    }
+
+    // Create tombstone object
+    const tombstone = {
+      id: existing.id,
+      _deleted: true,
+      _deletedAt: Date.now()
+    };
+
+    await gunPut(gun.get(path), tombstone);
+    return true;
+  } catch (error) {
+    throw error;
+  }
+}
+
+/**
+ * Delete all data under path prefix (tombstone)
+ * @param {Object} gun - Gun instance
+ * @param {string} path - Gun path prefix
+ * @returns {Promise<Object>} Deletion results { success: boolean, count: number }
+ */
+export async function deleteAll(gun, path) {
+  const items = await readAll(gun, path);
+  let count = 0;
+
+  for (const item of items) {
+    if (item && item.id) {
+      const itemPath = `${path}/${item.id}`;
+      await deleteData(gun, itemPath);
+      count++;
+    }
+  }
+
+  return { success: true, count };
+}
+
+/**
+ * Subscribe to data changes
+ * @param {Object} gun - Gun instance
+ * @param {string} path - Gun path
+ * @param {Function} callback - Called on data changes
+ * @param {Object} options - Subscription options
+ * @param {boolean} options.prefix - Subscribe to all items under path (default: auto-detect)
+ * @returns {Object} Subscription object with unsubscribe method
+ */
+export function subscribe(gun, path, callback, options = {}) {
+  // Detect if this is a prefix subscription
+  const pathParts = path.split('/');
+  const isPrefix = options.prefix !== undefined ? options.prefix : pathParts.length <= 3;
+
+  if (isPrefix) {
+    // Subscribe to all items under this prefix
+    const ref = gun.get(path);
+
+    ref.map().on((data, key) => {
+      if (data && !key.startsWith('_') && !data._deleted) {
+        callback(data, key);
+      }
+    });
+
+    return {
+      unsubscribe: () => {
+        try {
+          ref.off();
+        } catch (e) {
+          // Ignore cleanup errors
+        }
+      },
+    };
+  } else {
+    // Subscribe to single item
+    const listener = gun.get(path).on((data, key) => {
+      if (data && !data._deleted) {
+        callback(data, key);
+      }
+    });
+
+    return {
+      unsubscribe: () => {
+        try {
+          listener.off();
+        } catch (e) {
+          // Ignore cleanup errors
+        }
+      },
+    };
+  }
+}