holosphere 1.1.9 → 1.1.11

package/hologram.js

@@ -0,0 +1,156 @@
+// holo_hologram.js
+
+/**
+ * Creates a soul hologram object for a data item
+ * @param {HoloSphere} holoInstance - The HoloSphere instance.
+ * @param {string} holon - The holon where the original data is stored
+ * @param {string} lens - The lens where the original data is stored
+ * @param {object} data - The data to create a hologram for
+ * @returns {object} - A hologram object with id and soul
+ */
+export function createHologram(holoInstance, holon, lens, data) {
+    // Check if the input data is already a hologram
+    if (isHologram(data)) {
+        // If it is, just return its existing ID and Soul, ignoring the provided holon/lens
+        console.warn('createHologram called with data that is already a hologram. Reusing existing soul:', data.soul);
+        return {
+            id: data.id,
+            soul: data.soul
+        };
+    }
+
+    // Original logic: Input data is not a hologram, create a new soul path
+    if (!holon || !lens || !data || !data.id) {
+        throw new Error('createHologram: Missing required parameters for non-hologram data');
+    }
+
+    const soul = `${holoInstance.appname}/${holon}/${lens}/${data.id}`;
+    return {
+        id: data.id,
+        soul: soul
+    };
+}
+
+/**
+ * Parses a soul path into its components.
+ * @param {string} soul - The soul path (e.g., "app/holon/lens/key").
+ * @returns {object|null} - An object with appname, holon, lens, key, or null if invalid.
+ */
+export function parseSoulPath(soul) {
+    if (typeof soul !== 'string') return null;
+    const parts = soul.split('/');
+    if (parts.length < 4) return null; // Must have at least app/holon/lens/key
+
+    // Reconstruct key if it contained slashes (though generally disallowed by getNodeRef validation)
+    const key = parts.slice(3).join('/');
+
+    return {
+        appname: parts[0],
+        holon: parts[1],
+        lens: parts[2],
+        key: key
+    };
+}
+
+/**
+ * Checks if an object is a hologram.
+ * This function checks for the presence and type of `id` and `soul` properties,
+ * suitable for identifying holograms represented as plain JavaScript objects.
+ * It also performs a basic check that the `soul` contains '/' as expected for a path.
+ * @param {object | null | undefined} data - The data to check.
+ * @returns {boolean} - True if the object is considered a hologram.
+ */
+export function isHologram(data) {
+    if (!data || typeof data !== 'object') {
+        return false;
+    }
+    
+    // Basic check: Does it have an 'id' and a 'soul' which is a non-empty string?
+    if (data.id && typeof data.soul === 'string' && data.soul.length > 0) {
+         // Optional stricter check: Does the soul look like a valid path?
+         // This prevents objects like { id: 1, soul: "hello" } from being counted.
+         // We can use a simplified check here or rely on parseSoulPath failing later.
+         if (data.soul.includes('/')) { // Simple check for path structure
+            return true;
+         } 
+    }
+
+    return false;
+}
+
+/**
+ * Resolves a hologram to its actual data
+ * @param {HoloSphere} holoInstance - The HoloSphere instance.
+ * @param {object} hologram - The hologram to resolve
+ * @param {object} [options] - Optional parameters
+ * @param {boolean} [options.followHolograms=true] - Whether to follow nested holograms
+ * @param {Set<string>} [options.visited] - Internal use: Tracks visited souls to prevent loops
+ * @returns {Promise<object|null>} - The resolved data, null if resolution failed due to target not found, or the original hologram for circular/invalid cases.
+ */
+export async function resolveHologram(holoInstance, hologram, options = {}) {
+    if (!isHologram(hologram)) {
+        return hologram; // Not a hologram, return as is
+    }
+
+    const { followHolograms = true, visited = new Set() } = options;
+
+    // Check for circular hologram FIRST
+    if (hologram.soul && visited.has(hologram.soul)) {
+        console.warn(`!!! CIRCULAR hologram detected for soul: ${hologram.soul}. Returning original hologram.`);
+        throw new Error(`CIRCULAR_REFERENCE:${hologram.soul}`);
+    } else {
+        try {
+            // Handle direct soul hologram
+            if (hologram.soul) {
+                const soulInfo = parseSoulPath(hologram.soul);
+                if (!soulInfo) {
+                    console.warn(`Invalid soul format: ${hologram.soul}`);
+                    return hologram;
+                }
+
+                // Add current soul to visited set for THIS resolution path
+                const nextVisited = new Set(visited);
+                nextVisited.add(hologram.soul);
+
+                console.log(`Resolving hologram with soul: ${hologram.soul}`);
+
+                // Get original data
+                const originalData = await holoInstance.get(
+                    soulInfo.holon,
+                    soulInfo.lens,
+                    soulInfo.key,
+                    null,
+                    {
+                        resolveHolograms: followHolograms,
+                        visited: nextVisited
+                    }
+                );
+
+                console.log('### resolveHologram received originalData:', originalData);
+
+                if (originalData) {
+                    console.log(`### Returning RESOLVED data for soul: ${hologram.soul}`);
+                    // Structure for the returned object - isHologram (top-level) is removed
+                    return {
+                        ...originalData,
+                        _meta: {
+                            ...(originalData._meta || {}), // Preserve original _meta
+                            resolvedFromHologram: true,    // This is now the primary indicator
+                            hologramSoul: hologram.soul     // Clarified meta field
+                        }
+                    };
+                } else {
+                    console.warn(`!!! Original data NOT FOUND for soul: ${hologram.soul}. Returning null.`);
+                    return null;
+                }
+            } else {
+                 // Should not happen if isHologram() passed
+                 console.warn('!!! resolveHologram called with object missing soul:', hologram);
+                 return hologram;
+            }
+        } catch (error) {
+            console.error(`!!! Error resolving hologram: ${error.message}`, error);
+            return hologram; // Return original hologram on error
+        }
+    }
+} 

package/holosphere.d.ts

@@ -2,8 +2,8 @@
  * Federation propagation options interface
  */
 interface PropagationOptions {
-  /** Whether to use references instead of duplicating data (default: true) */
-  useReferences?: boolean;
+  /** Whether to use holograms instead of duplicating data (default: true) */
+  useHolograms?: boolean;
   /** Specific target spaces to propagate to (default: all federated spaces) */
   targetSpaces?: string[];
   /** Password for accessing the source holon (if needed) */
@@ -18,14 +18,37 @@ interface PutOptions {
   autoPropagate?: boolean;
   /** Additional options to pass to propagate */
   propagationOptions?: PropagationOptions;
+  /** Whether to disable hologram redirection logic when putting data (default: false) */
+  disableHologramRedirection?: boolean;
 }
 
 /**
  * Get options interface
  */
 interface GetOptions {
-  /** Whether to automatically resolve federation references (default: true) */
-  resolveReferences?: boolean;
+  /** Whether to automatically resolve holograms (default: true) */
+  resolveHolograms?: boolean;
+  /** Options passed to the schema validator */
+  validationOptions?: object;
+}
+
+/**
+ * Resolve Hologram options interface
+ */
+interface ResolveHologramOptions {
+  /** Whether to follow nested holograms (default: true) */
+  followHolograms?: boolean;
+  /** Internal use: Tracks visited souls to prevent loops */
+  visited?: Set<string>;
+}
+
+/**
+ * Represents a Hologram object, typically containing an id and a soul path.
+ */
+interface Hologram {
+  id: string;
+  soul: string;
+  [key: string]: any; // Allow other properties, e.g., _federation
 }
 
 /**
@@ -92,11 +115,31 @@ interface PropagationResult {
   message?: string;
 }
 
+/**
+ * Result from a put operation
+ */
+interface PutResult {
+  /** Indicates if the put operation was successful */
+  success: boolean;
+  /** Indicates if the data ultimately put at the path was a hologram */
+  isHologramAtPath?: boolean;
+  /** The final holon where data was put (after potential redirection) */
+  pathHolon: string;
+  /** The final lens where data was put (after potential redirection) */
+  pathLens: string;
+  /** The final key under which data was put (after potential redirection) */
+  pathKey: string;
+  /** Result of any automatic propagation, if it occurred */
+  propagationResult?: PropagationResult | null;
+  /** Error message if the put operation failed at some point */
+  error?: string;
+}
+
 declare class HoloSphere {
     private appname;
     private strict;
     private validator;
-    private gun;
+    public gun;
     private sea;
     private openai?;
     private subscriptions;
@@ -110,6 +153,12 @@ declare class HoloSphere {
      */
     constructor(appname: string, strict?: boolean, openaikey?: string | null, gunInstance?: any);
 
+    /**
+     * Gets the Gun instance.
+     * @returns {any} - The Gun instance.
+     */
+    getGun(): any;
+
     // ================================ SCHEMA FUNCTIONS ================================
 
     /**
@@ -138,7 +187,7 @@ declare class HoloSphere {
      * @param {PutOptions} [options] - Additional options
      * @returns {Promise<any>} - Returns result object if successful
      */
-    put(holon: string, lens: string, data: object, password?: string | null, options?: PutOptions): Promise<any>;
+    put(holon: string, lens: string, data: object, password?: string | null, options?: PutOptions): Promise<PutResult>;
 
     /**
      * Retrieves content from the specified holon and lens.
@@ -232,6 +281,32 @@ declare class HoloSphere {
      */
     deleteNode(holon: string, lens: string, key: string): Promise<boolean>;
 
+    // ================================ HOLOGRAM FUNCTIONS ================================
+
+    /**
+     * Creates a soul hologram object for a data item.
+     * @param {string} holon - The holon where the original data is stored.
+     * @param {string} lens - The lens where the original data is stored.
+     * @param {object} data - The data to create a hologram for. Must have an 'id' field.
+     * @returns {Hologram} - A hologram object containing id and soul.
+     */
+    createHologram(holon: string, lens: string, data: { id: string, [key: string]: any }): Hologram;
+
+    /**
+     * Checks if an object is a hologram (has id and soul).
+     * @param {any} data - The data to check.
+     * @returns {boolean} - True if the object is considered a hologram.
+     */
+    isHologram(data: any): data is Hologram;
+
+    /**
+     * Resolves a hologram to its actual data by following its soul path.
+     * @param {Hologram} hologram - The hologram object to resolve.
+     * @param {ResolveHologramOptions} [options] - Options for resolution.
+     * @returns {Promise<object|null>} - The resolved data, null if not found, or the original hologram in case of loops/errors.
+     */
+    resolveHologram(hologram: Hologram, options?: ResolveHologramOptions): Promise<object | null>;
+
     // ================================ GLOBAL FUNCTIONS ================================
 
     /**
@@ -364,9 +439,12 @@ declare class HoloSphere {
      * @param {string} [password1] - Optional password for the first holon
      * @param {string} [password2] - Optional password for the second holon
      * @param {boolean} [bidirectional=true] - Whether to set up bidirectional notifications automatically
+     * @param {object} [lensConfig] - Optional lens-specific configuration
+     * @param {string[]} [lensConfig.federate] - List of lenses to federate (default: all)
+     * @param {string[]} [lensConfig.notify] - List of lenses to notify (default: all)
      * @returns {Promise<boolean>} - True if federation was created successfully
      */
-    federate(holonId1: string, holonId2: string, password1?: string | null, password2?: string | null, bidirectional?: boolean): Promise<boolean>;
+    federate(holonId1: string, holonId2: string, password1?: string | null, password2?: string | null, bidirectional?: boolean, lensConfig?: { federate?: string[], notify?: string[] }): Promise<boolean>;
 
     /**
      * Subscribes to federation notifications for a holon
@@ -386,6 +464,15 @@ declare class HoloSphere {
      */
     getFederation(holonId: string, password?: string | null): Promise<FederationInfo | null>;
 
+    /**
+     * Retrieves the lens-specific configuration for a federation link between two holons.
+     * @param {string} holonId - The ID of the source holon.
+     * @param {string} targetHolonId - The ID of the target holon in the federation link.
+     * @param {string} [password] - Optional password for the source holon.
+     * @returns {Promise<{ federate: string[], notify: string[] } | null>} - An object with 'federate' and 'notify' arrays, or null if not found.
+     */
+    getFederatedConfig(holonId: string, targetHolonId: string, password?: string | null): Promise<{ federate: string[], notify: string[] } | null>;
+
     /**
      * Removes a federation relationship between holons
      * @param {string} holonId1 - The first holon ID