holosphere 1.1.20 → 2.0.0-alpha0

package/node.js

@@ -1,246 +0,0 @@
-// holo_node.js
-
-/**
- * Stores a specific gun node in a given holon and lens.
- * @param {HoloSphere} holoInstance - The HoloSphere instance.
- * @param {string} holon - The holon identifier.
- * @param {string} lens - The lens under which to store the node.
- * @param {object} data - The node to store.
- */
-export async function putNode(holoInstance, holon, lens, data) {
-    if (!holon || !lens || !data) {
-        throw new Error('putNode: Missing required parameters');
-    }
-
-    return new Promise((resolve, reject) => {
-        try {
-            // Remove isHologram field before storing - NO LONGER NEEDED
-            // if (data && data.isHologram !== undefined) {
-            // delete data.isHologram;
-            // }
-            
-            // Check if the data being stored is a hologram
-            const isHologram = data.value && holoInstance.isHologram(data.value);
-            
-            holoInstance.gun.get(holoInstance.appname)
-                .get(holon)
-                .get(lens)
-                .get('value')  // Store at 'value' key
-                .put(data.value, ack => {  // Store the value directly
-                    if (ack.err) {
-                        reject(new Error(ack.err));
-                    } else {
-                        // --- Start: Hologram Tracking Logic (for data *being put*, if it's a hologram) ---
-                        if (isHologram) {
-                            try {
-                                const storedDataSoulInfo = holoInstance.parseSoulPath(data.value.soul);
-                                if (storedDataSoulInfo) {
-                                    const targetNodeRef = holoInstance.getNodeRef(data.value.soul); // Target of the data *being put*
-                                    // Soul of the hologram that was *actually stored* at holon/lens/value
-                                    const storedHologramInstanceSoul = `${holoInstance.appname}/${holon}/${lens}/value`;
-                                    
-                                                                targetNodeRef.get('_holograms').get(storedHologramInstanceSoul).put(true);
-                        } else {
-                                    console.warn(`Data (ID: ${data.id}) being put is a hologram, but could not parse its soul ${data.value.soul} for tracking.`);
-                                }
-                            } catch (trackingError) {
-                                console.warn(`Error updating _holograms set for the target of the data being put (data ID: ${data.id}, soul: ${data.value.soul}):`, trackingError);
-                            }
-                        }
-                        // --- End: Hologram Tracking Logic ---
-                        
-                        resolve(true);
-                    }
-                });
-        } catch (error) {
-            reject(error);
-        }
-    });
-}
-
-/**
- * Retrieves a specific gun node from the specified holon and lens.
- * @param {HoloSphere} holoInstance - The HoloSphere instance.
- * @param {string} holon - The holon identifier.
- * @param {string} lens - The lens identifier.
- * @param {string} key - The specific key to retrieve.
- * @returns {Promise<any>} - The retrieved node or null if not found.
- */
-export async function getNode(holoInstance, holon, lens, key) {
-    if (!holon || !lens || !key) {
-        throw new Error('getNode: Missing required parameters');
-    }
-
-    return new Promise((resolve, reject) => {
-        try {
-            holoInstance.gun.get(holoInstance.appname)
-                .get(holon)
-                .get(lens)
-                .get(key)
-                .once((data) => {
-                    if (!data) {
-                        resolve(null);
-                        return;
-                    }
-                    resolve(data);  // Return the data directly
-                });
-        } catch (error) {
-            reject(error);
-        }
-    });
-}
-
-/**
- * Retrieves a Gun node reference using its soul path
- * @param {HoloSphere} holoInstance - The HoloSphere instance.
- * @param {string} soul - The soul path of the node
- * @returns {Gun.ChainReference} - The Gun node reference
- */
-export function getNodeRef(holoInstance, soul) {
-    if (typeof soul !== 'string' || !soul) {
-        throw new Error('getNodeRef: Invalid soul parameter');
-    }
-
-    const parts = soul.split('/').filter(part => {
-        if (!part.trim() || /[<>:"/\\|?*]/.test(part)) { // Escaped backslash for regex
-            throw new Error('getNodeRef: Invalid path segment');
-        }
-        return part.trim();
-    });
-
-    if (parts.length === 0) {
-        throw new Error('getNodeRef: Invalid soul format');
-    }
-
-    let ref = holoInstance.gun.get(holoInstance.appname);
-    parts.forEach(part => {
-        ref = ref.get(part);
-    });
-    return ref;
-}
-
-/**
- * Retrieves a node directly using its soul path
- * @param {HoloSphere} holoInstance - The HoloSphere instance.
- * @param {string} soul - The soul path of the node
- * @returns {Promise<any>} - The retrieved node or null if not found.
- */
-export async function getNodeBySoul(holoInstance, soul) {
-    if (!soul) {
-        throw new Error('getNodeBySoul: Missing soul parameter');
-    }
-
-    console.log(`getNodeBySoul: Accessing soul ${soul}`);
-
-    return new Promise((resolve, reject) => {
-        try {
-            const ref = getNodeRef(holoInstance, soul); // Use the exported getNodeRef
-            ref.once((data) => {
-                console.log(`getNodeBySoul: Retrieved data:`, data);
-                if (!data) {
-                    resolve(null);
-                    return;
-                }
-                resolve(data);  // Return the data directly
-            });
-        } catch (error) {
-            console.error(`getNodeBySoul error:`, error);
-            reject(error);
-        }
-    });
-}
-
-/**
- * Deletes a specific gun node from a given holon and lens.
- * @param {HoloSphere} holoInstance - The HoloSphere instance.
- * @param {string} holon - The holon identifier.
- * @param {string} lens - The lens identifier.
- * @param {string} key - The key of the node to delete.
- * @returns {Promise<boolean>} - Returns true if successful
- */
-export async function deleteNode(holoInstance, holon, lens, key) {
-    if (!holon || !lens || !key) {
-        throw new Error('deleteNode: Missing required parameters');
-    }
-
-    try {
-        const dataPath = holoInstance.gun.get(holoInstance.appname).get(holon).get(lens).get(key);
-
-        // --- Start: Hologram Tracking Removal ---
-        let trackingRemovalPromise = Promise.resolve(); // Default to resolved promise
-        
-        // 1. Get the data first to check if it's a hologram
-        const rawDataToDelete = await new Promise((resolve) => dataPath.once(resolve));
-        let dataToDelete = null;
-        try {
-            if (typeof rawDataToDelete === 'string') {
-                dataToDelete = JSON.parse(rawDataToDelete);
-            } else {
-                // Handle cases where it might already be an object (though likely string)
-                dataToDelete = rawDataToDelete; 
-            }
-        } catch(e) {
-            console.warn("[deleteNode] Could not JSON parse data for deletion check:", rawDataToDelete, e);
-            dataToDelete = null; // Ensure it's null if parsing fails
-        }
-
-        // 2. If it is a hologram, try to remove its reference from the target
-        const isDataHologram = dataToDelete && holoInstance.isHologram(dataToDelete);
-        
-        if (isDataHologram) {
-            try {
-                const targetSoul = dataToDelete.soul;
-                const targetSoulInfo = holoInstance.parseSoulPath(targetSoul);
-                
-                if (targetSoulInfo) {
-                    const targetNodeRef = holoInstance.getNodeRef(targetSoul);
-                    // putNode stores at the 'value' key, not at the data.id key
-                    const deletedHologramSoul = `${holoInstance.appname}/${holon}/${lens}/value`;
-
-                    // Create a promise that resolves when the hologram is removed from the list
-                    trackingRemovalPromise = new Promise((resolveTrack) => { // No reject needed, just warn on error
-                        targetNodeRef.get('_holograms').get(deletedHologramSoul).put(null, (ack) => { // Remove the hologram entry completely
-                            if (ack.err) {
-                                console.warn(`[deleteNode] Error removing hologram ${deletedHologramSoul} from target ${targetSoul}:`, ack.err);
-                                                    }
-                        resolveTrack(); // Resolve regardless of ack error to not block main delete
-                        });
-                    });
-                } else {
-                    console.warn(`Could not parse target soul ${targetSoul} for hologram tracking removal during deleteNode.`);
-                }
-            } catch (trackingError) {
-                console.warn(`Error initiating hologram reference removal from target ${dataToDelete.soul} during deleteNode:`, trackingError);
-                // Ensure trackingRemovalPromise remains resolved if setup fails
-                trackingRemovalPromise = Promise.resolve(); 
-            }
-        }
-        // --- End: Hologram Tracking Removal ---
-
-        // 3. Wait for the tracking removal attempt to be acknowledged
-        await trackingRemovalPromise;
-
-        // 4. Proceed with the actual deletion of the hologram node itself
-        return new Promise((resolve, reject) => {
-            dataPath.put(null, ack => {
-                if (ack.err) {
-                    reject(new Error(ack.err));
-                } else {
-                    resolve(true);
-                }
-            });
-        });
-    } catch (error) {
-        console.error('Error in deleteNode:', error);
-        throw error;
-    }
-} 
-
-// Export all node operations as default
-export default {
-    putNode,
-    getNode,
-    getNodeRef,
-    getNodeBySoul,
-    deleteNode
-}; 

package/schema.js

@@ -1,139 +0,0 @@
-// holo_schema.js
-
-import Ajv2019 from 'ajv/dist/2019.js';
-
-/**
- * Sets the JSON schema for a specific lens.
- * @param {HoloSphere} holoInstance - The HoloSphere instance.
- * @param {string} lens - The lens identifier.
- * @param {object} schema - The JSON schema to set.
- * @returns {Promise<boolean>} - Resolves when the schema is set.
- */
-export async function setSchema(holoInstance, lens, schema) {
-    if (!lens || !schema) {
-        throw new Error('setSchema: Missing required parameters');
-    }
-
-    // Basic schema validation
-    if (!schema.type || typeof schema.type !== 'string') {
-        throw new Error('setSchema: Schema must have a type field');
-    }
-
-    const metaSchema = {
-        type: 'object',
-        required: ['type', 'properties'],
-        properties: {
-            type: { type: 'string' },
-            properties: {
-                type: 'object',
-                additionalProperties: {
-                    type: 'object',
-                    required: ['type'],
-                    properties: {
-                        type: { type: 'string' }
-                    }
-                }
-            },
-            required: {
-                type: 'array',
-                items: { type: 'string' }
-            }
-        }
-    };
-
-    // Use the validator from the instance
-    const valid = holoInstance.validator.validate(metaSchema, schema);
-    if (!valid) {
-        throw new Error(`Invalid schema structure: ${JSON.stringify(holoInstance.validator.errors)}`);
-    }
-
-    if (!schema.properties || typeof schema.properties !== 'object') {
-        throw new Error('Schema must have properties in strict mode');
-    }
-
-    if (!schema.required || !Array.isArray(schema.required) || schema.required.length === 0) {
-        throw new Error('Schema must have required fields in strict mode');
-    }
-
-    // Store schema in global table with lens as key using instance's method
-    await holoInstance.putGlobal('schemas', {
-        id: lens,
-        schema: schema,
-        timestamp: Date.now()
-    });
-
-    // Update the instance's cache with the new schema
-    holoInstance.schemaCache.set(lens, {
-        schema,
-        timestamp: Date.now()
-    });
-
-    return true;
-}
-
-/**
- * Retrieves the JSON schema for a specific lens.
- * @param {HoloSphere} holoInstance - The HoloSphere instance.
- * @param {string} lens - The lens identifier.
- * @param {object} [options] - Additional options
- * @param {boolean} [options.useCache=true] - Whether to use the schema cache
- * @param {number} [options.maxCacheAge=3600000] - Maximum cache age in milliseconds (default: 1 hour)
- * @returns {Promise<object|null>} - The retrieved schema or null if not found.
- */
-export async function getSchema(holoInstance, lens, options = {}) {
-    if (!lens) {
-        throw new Error('getSchema: Missing lens parameter');
-    }
-
-    const { useCache = true, maxCacheAge = 3600000 } = options;
-
-    // Check instance's cache first if enabled
-    if (useCache && holoInstance.schemaCache.has(lens)) {
-        const cached = holoInstance.schemaCache.get(lens);
-        const cacheAge = Date.now() - cached.timestamp;
-
-        // Use cache if it's fresh enough
-        if (cacheAge < maxCacheAge) {
-            return cached.schema;
-        }
-    }
-
-    // Cache miss or expired, fetch from storage using instance's method
-    const schemaData = await holoInstance.getGlobal('schemas', lens);
-
-    if (!schemaData || !schemaData.schema) {
-        return null;
-    }
-
-    // Update instance's cache with fetched schema
-    holoInstance.schemaCache.set(lens, {
-        schema: schemaData.schema,
-        timestamp: Date.now()
-    });
-
-    return schemaData.schema;
-}
-
-/**
- * Clears the schema cache or a specific schema from the cache.
- * @param {HoloSphere} holoInstance - The HoloSphere instance.
- * @param {string} [lens] - Optional lens to clear from cache. If not provided, clears entire cache.
- * @returns {boolean} - Returns true if successful
- */
-export function clearSchemaCache(holoInstance, lens = null) {
-    if (lens) {
-        // Clear specific schema from instance's cache
-        return holoInstance.schemaCache.delete(lens);
-    } else {
-        // Clear entire instance's cache
-        holoInstance.schemaCache.clear();
-        return true;
-    }
-} 
-
-// Export all schema operations as default
-export default {
-    setSchema,
-    getSchema,
-    clearSchemaCache
-}; 

package/utils.js

@@ -1,302 +0,0 @@
-// holo_utils.js
-import * as h3 from 'h3-js';
-
-/**
- * Converts latitude and longitude to a holon identifier.
- * @param {number} lat - The latitude.
- * @param {number} lng - The longitude.
- * @param {number} resolution - The resolution level.
- * @returns {Promise<string>} - The resulting holon identifier.
- */
-export async function getHolon(lat, lng, resolution) { // Doesn't need holoInstance
-    return h3.latLngToCell(lat, lng, resolution);
-}
-
-/**
- * Retrieves all containing holonagons at all scales for given coordinates.
- * @param {number} lat - The latitude.
- * @param {number} lng - The longitude.
- * @returns {Array<string>} - List of holon identifiers.
- */
-export function getScalespace(lat, lng) { // Doesn't need holoInstance
-    let list = []
-    let cell = h3.latLngToCell(lat, lng, 14);
-    list.push(cell)
-    for (let i = 13; i >= 0; i--) {
-        list.push(h3.cellToParent(cell, i))
-    }
-    return list
-}
-
-/**
- * Retrieves all containing holonagons at all scales for a given holon.
- * @param {string} holon - The holon identifier.
- * @returns {Array<string>} - List of holon identifiers.
- */
-export function getHolonScalespace(holon) { // Doesn't need holoInstance
-    let list = []
-    let res = h3.getResolution(holon)
-    for (let i = res; i >= 0; i--) {
-        list.push(h3.cellToParent(holon, i))
-    }
-    return list
-}
-
-/**
- * Subscribes to changes in a specific holon and lens.
- * @param {HoloSphere} holoInstance - The HoloSphere instance.
- * @param {string} holon - The holon identifier.
- * @param {string} lens - The lens to subscribe to.
- * @param {function} callback - The callback to execute on changes.
- * @returns {Promise<object>} - Subscription object with unsubscribe method
- */
-export async function subscribe(holoInstance, holon, lens, callback) {
-    if (!holon || !lens) {
-        throw new Error('subscribe: Missing holon or lens parameters:', holon, lens);
-    }
-
-    if (!callback || typeof callback !== 'function') {
-        throw new Error('subscribe: Callback must be a function');
-    }
-
-    const subscriptionId = holoInstance.generateId(); // Use instance's generateId
-
-    try {
-        // Get the Gun chain up to the map()
-        const mapChain = holoInstance.gun.get(holoInstance.appname).get(holon).get(lens).map();
-
-        // Create the subscription by calling .on() on the map chain
-        const gunListener = mapChain.on(async (data, key) => { // Renamed variable
-            // Check if subscription ID still exists (might have been unsubscribed)
-            if (!holoInstance.subscriptions[subscriptionId]) {
-                return;
-            }
-
-            if (data) {
-                try {
-                    let parsed = await holoInstance.parse(data);
-                    if (parsed && holoInstance.isHologram(parsed)) {
-                        const resolved = await holoInstance.resolveHologram(parsed, { followHolograms: true });
-                        if (resolved !== parsed) {
-                            parsed = resolved;
-                        }
-                    }
-
-                    // Check again if subscription ID still exists before calling callback
-                    if (holoInstance.subscriptions[subscriptionId]) {
-                        callback(parsed, key);
-                    }
-                } catch (error) {
-                    console.error('Error processing subscribed data:', error);
-                }
-            }
-        });
-
-        // Store the subscription with its ID on the instance
-        holoInstance.subscriptions[subscriptionId] = {
-            id: subscriptionId,
-            holon,
-            lens,
-            callback,
-            mapChain: mapChain,       // Store the map chain
-            gunListener: gunListener  // Store the listener too (optional, maybe needed for close?)
-        };
-
-        // Return an object with unsubscribe method
-        return {
-            unsubscribe: async () => {
-                const sub = holoInstance.subscriptions[subscriptionId];
-                if (!sub) {
-                    return;
-                }
-
-                try {
-                    // Turn off the Gun subscription using the stored mapChain reference
-                    if (sub.mapChain) { // Check if mapChain exists
-                        sub.mapChain.off(); // Call off() on the chain where .on() was attached
-                        // Optional: Add delay back? Let's omit for now.
-                        // await new Promise(res => setTimeout(res, 50));
-                    } // We might not need to call off() on gunListener explicitly
-
-                    // Remove from subscriptions object AFTER turning off listener
-                    delete holoInstance.subscriptions[subscriptionId];
-                } catch (error) {
-                    console.error(`Error during unsubscribe logic for ${subscriptionId}:`, error);
-                }
-            }
-        };
-    } catch (error) {
-        console.error('Error creating subscription:', error);
-        throw error;
-    }
-}
-
-/**
- * Notifies subscribers about data changes
- * @param {HoloSphere} holoInstance - The HoloSphere instance.
- * @param {object} data - The data to notify about
- * @private
- */
-export function notifySubscribers(holoInstance, data) {
-    if (!data || !data.holon || !data.lens) {
-        return;
-    }
-
-    try {
-        Object.values(holoInstance.subscriptions).forEach(subscription => {
-            if (subscription.holon === data.holon &&
-                subscription.lens === data.lens) {
-                try {
-                    if (subscription.callback && typeof subscription.callback === 'function') {
-                        subscription.callback(data);
-                    }
-                } catch (error) {
-                    console.warn('Error in subscription callback:', error);
-                }
-            }
-        });
-    } catch (error) {
-        console.warn('Error notifying subscribers:', error);
-    }
-}
-
-// Add ID generation method
-export function generateId() { // Doesn't need holoInstance
-    return Date.now().toString(10) + Math.random().toString(2);
-}
-
-/**
- * Closes the HoloSphere instance and cleans up resources.
- * @param {HoloSphere} holoInstance - The HoloSphere instance.
- * @returns {Promise<void>}
- */
-export async function close(holoInstance) {
-    try {
-        if (holoInstance.gun) {
-            // Unsubscribe from all subscriptions
-            const subscriptionIds = Object.keys(holoInstance.subscriptions);
-            for (const id of subscriptionIds) {
-                try {
-                    const subscription = holoInstance.subscriptions[id];
-                    if (subscription) {
-                        // Turn off the Gun subscription using the stored mapChain reference
-                        if (subscription.mapChain) {
-                            subscription.mapChain.off();
-                        } // Also turn off listener directly? Might be redundant.
-                        // if (subscription.gunListener) {
-                        //     subscription.gunListener.off();
-                        // }
-                    }
-                } catch (error) {
-                    console.warn(`Error cleaning up subscription ${id}:`, error);
-                }
-            }
-
-            // Clear subscriptions
-            holoInstance.subscriptions = {};
-
-            // Clear schema cache using instance method
-            holoInstance.clearSchemaCache();
-
-            // Close Gun connections
-            if (holoInstance.gun.back) {
-                try {
-                    // Clean up mesh connections
-                    const mesh = holoInstance.gun.back('opt.mesh');
-                    if (mesh) {
-                        // Clean up mesh.hear
-                        if (mesh.hear) {
-                            try {
-                                // Safely clear mesh.hear without modifying function properties
-                                const hearKeys = Object.keys(mesh.hear);
-                                for (const key of hearKeys) {
-                                    // Check if it's an array before trying to clear it
-                                    if (Array.isArray(mesh.hear[key])) {
-                                        mesh.hear[key] = [];
-                                    }
-                                }
-
-                                // Create a new empty object for mesh.hear
-                                // Only if mesh.hear is not a function
-                                if (typeof mesh.hear !== 'function') {
-                                    mesh.hear = {};
-                                }
-                            } catch (meshError) {
-                                console.warn('Error cleaning up Gun mesh hear:', meshError);
-                            }
-                        }
-
-                        // Close any open sockets in the mesh
-                        if (mesh.way) {
-                            try {
-                                Object.values(mesh.way).forEach(connection => {
-                                    if (connection && connection.wire && connection.wire.close) {
-                                        connection.wire.close();
-                                    }
-                                });
-                            } catch (sockError) {
-                                console.warn('Error closing mesh sockets:', sockError);
-                            }
-                        }
-
-                        // Clear the peers list
-                        if (mesh.opt && mesh.opt.peers) {
-                            mesh.opt.peers = {};
-                        }
-                    }
-
-                    // Attempt to clean up any TCP connections
-                    if (holoInstance.gun.back('opt.web')) {
-                        try {
-                            const server = holoInstance.gun.back('opt.web');
-                            if (server && server.close) {
-                                server.close();
-                            }
-                        } catch (webError) {
-                            console.warn('Error closing web server:', webError);
-                        }
-                    }
-                } catch (error) {
-                    console.warn('Error accessing Gun mesh:', error);
-                }
-            }
-
-            // Clear all Gun instance listeners
-            try {
-                holoInstance.gun.off();
-            } catch (error) {
-                console.warn('Error turning off Gun listeners:', error);
-            }
-
-            // Wait a moment for cleanup to complete
-            await new Promise(resolve => setTimeout(resolve, 100));
-        }
-
-        console.log('HoloSphere instance closed successfully');
-    } catch (error) {
-        console.error('Error closing HoloSphere instance:', error);
-    }
-}
-
-/**
- * Creates a namespaced username for Gun authentication
- * @param {HoloSphere} holoInstance - The HoloSphere instance.
- * @param {string} holonId - The holon ID
- * @returns {string} - Namespaced username
- */
-export function userName(holoInstance, holonId) {
-    if (!holonId) return null;
-    return `${holoInstance.appname}:${holonId}`;
-} 
-
-// Export all utility operations as default
-export default {
-    getHolon,
-    getScalespace,
-    getHolonScalespace,
-    subscribe,
-    notifySubscribers,
-    generateId,
-    close,
-    userName
-};