shogun-core 3.3.6 → 3.3.8

package/dist/gundb/api.js

@@ -1,7 +1,13 @@
 "use strict";
 /**
- * Simplified API layer to reduce complexity for common use cases.
- * Provides quick-start methods that wrap the full DataBase functionality.
+ * Simplified API layer focused on valuable helper methods.
+ * Provides quick-start initialization and high-level convenience methods.
+ *
+ * For basic operations (get, put, set, remove, auth), use DataBase directly.
+ * This class provides:
+ * - Quick initialization helpers (QuickStart, AutoQuickStart)
+ * - Array/Object conversion utilities for GunDB
+ * - High-level user data helpers (profile, settings, collections)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AutoQuickStart = exports.QuickStart = exports.SimpleGunAPI = void 0;
@@ -10,7 +16,8 @@ exports.quickStart = quickStart;
 exports.autoQuickStart = autoQuickStart;
 const db_1 = require("./db");
 /**
- * Simple API wrapper that provides common operations with minimal complexity.
+ * Simple API wrapper that provides high-level helper methods.
+ * For basic operations, use the DataBase instance directly via the `database` property.
  */
 class SimpleGunAPI {
     /**
@@ -20,307 +27,24 @@ class SimpleGunAPI {
     constructor(db) {
         this.db = db;
     }
-    // =========================
-    // Quick data operations
-    // =========================
-    /**
-     * Get data at a given path.
-     * @param path The path to retrieve data from.
-     * @returns The data at the path, or null if not found or on error.
-     */
-    async get(path) {
-        try {
-            const result = await this.db.getData(path);
-            return result;
-        }
-        catch (error) {
-            console.warn(`Failed to get data from ${path}:`, error);
-            return null;
-        }
-    }
-    /**
-     * Get the Gun node at a given path for chaining operations.
-     * @param path The path to the node.
-     * @returns The Gun node.
-     */
-    getNode(path) {
-        return this.db.get(path);
-    }
-    /**
-     * Get the Gun node at a given path for direct chaining.
-     * @param path The path to the node.
-     * @returns The Gun node.
-     */
-    node(path) {
-        return this.db.get(path);
-    }
-    /**
-     * Get a chainable wrapper for a Gun node at a given path.
-     * @param path The path to the node.
-     * @returns An object with chainable methods: get, put, set, once, then, map.
-     */
-    chain(path) {
-        const node = this.db.get(path);
-        return {
-            get: (subPath) => this.chain(`${path}/${subPath}`),
-            put: async (data) => {
-                try {
-                    const result = await this.db.put(path, data);
-                    return result;
-                }
-                catch (error) {
-                    console.warn(`Failed to put data to ${path}:`, error);
-                    return { err: String(error) };
-                }
-            },
-            set: async (data) => {
-                try {
-                    const result = await this.db.set(path, data);
-                    return result;
-                }
-                catch (error) {
-                    console.warn(`Failed to set data to ${path}:`, error);
-                    return { err: String(error) };
-                }
-            },
-            once: async () => {
-                try {
-                    return await this.db.getData(path);
-                }
-                catch (error) {
-                    console.warn(`Failed to get data from ${path}:`, error);
-                    return null;
-                }
-            },
-            then: async () => {
-                try {
-                    return await this.db.getData(path);
-                }
-                catch (error) {
-                    console.warn(`Failed to get data from ${path}:`, error);
-                    return null;
-                }
-            },
-            map: (callback) => {
-                return node.map ? node.map(callback) : null;
-            },
-        };
-    }
-    /**
-     * Put data at a given path.
-     * @param path The path to put data to.
-     * @param data The data to put.
-     * @returns The GunMessagePut result.
-     */
-    async put(path, data) {
-        try {
-            const result = await this.db.put(path, data);
-            return result;
-        }
-        catch (error) {
-            console.warn(`Failed to put data to ${path}:`, error);
-            return { err: String(error) };
-        }
-    }
-    /**
-     * Set data at a given path (alternative to put).
-     * @param path The path to set data to.
-     * @param data The data to set.
-     * @returns The GunMessagePut result.
-     */
-    async set(path, data) {
-        try {
-            const result = await this.db.set(path, data);
-            return result;
-        }
-        catch (error) {
-            console.warn(`Failed to set data to ${path}:`, error);
-            return { err: String(error) };
-        }
-    }
     /**
-     * Remove data at a given path.
-     * @param path The path to remove data from.
-     * @returns The GunMessagePut result.
-     */
-    async remove(path) {
-        try {
-            const result = await this.db.remove(path);
-            return result;
-        }
-        catch (error) {
-            console.warn(`Failed to remove data from ${path}:`, error);
-            return { err: String(error) };
-        }
-    }
-    // =========================
-    // Quick authentication
-    // =========================
-    /**
-     * Log in a user.
-     * @param username The username.
-     * @param password The password.
-     * @returns The user info if successful, or null.
-     */
-    async login(username, password) {
-        try {
-            const result = await this.db.login(username, password);
-            if (result.success && result.userPub) {
-                return {
-                    userPub: result.userPub,
-                    username: result.username || username,
-                };
-            }
-            return null;
-        }
-        catch (error) {
-            console.warn(`Login failed for ${username}:`, error);
-            return null;
-        }
-    }
-    /**
-     * Sign up a new user.
-     * @param username The username.
-     * @param password The password.
-     * @returns The user info if successful, or null.
-     */
-    async signup(username, password) {
-        try {
-            const result = await this.db.signUp(username, password);
-            if (result.success && result.userPub) {
-                return {
-                    userPub: result.userPub,
-                    username: result.username || username,
-                };
-            }
-            return null;
-        }
-        catch (error) {
-            console.warn(`Signup failed for ${username}:`, error);
-            return null;
-        }
-    }
-    /**
-     * Log out the current user.
-     */
-    logout() {
-        this.db.logout();
-    }
-    /**
-     * Check if a user is currently logged in.
-     * @returns True if logged in, false otherwise.
-     */
-    isLoggedIn() {
-        return this.db.isLoggedIn();
-    }
-    // =========================
-    // Quick user data operations
-    // =========================
-    /**
-     * Get user data at a given path (requires login).
-     * @param path The path to the user data.
-     * @returns The user data, or null if not found or on error.
-     */
-    async getUserData(path) {
-        try {
-            if (!this.isLoggedIn()) {
-                console.warn("User not logged in");
-                return null;
-            }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return null;
-            }
-            const data = await this.db.user.get(path).once().then();
-            return data;
-        }
-        catch (error) {
-            console.warn(`Failed to get user data from ${path}:`, error);
-            return null;
-        }
-    }
-    /**
-     * Put user data at a given path (requires login).
-     * @param path The path to put data to.
-     * @param data The data to put.
-     * @returns True if successful, false otherwise.
-     */
-    async putUserData(path, data) {
-        try {
-            if (!this.isLoggedIn()) {
-                console.warn("User not logged in");
-                return false;
-            }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return false;
-            }
-            await this.db.user.get(path).put(data).then();
-            return true;
-        }
-        catch (error) {
-            console.warn(`Failed to put user data to ${path}:`, error);
-            return false;
-        }
-    }
-    /**
-     * Set user data at a given path (alternative to put, requires login).
-     * @param path The path to set data to.
-     * @param data The data to set.
-     * @returns True if successful, false otherwise.
-     */
-    async setUserData(path, data) {
-        try {
-            if (!this.isLoggedIn()) {
-                console.warn("User not logged in");
-                return false;
-            }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return false;
-            }
-            await this.db.user.get(path).put(data).then();
-            return true;
-        }
-        catch (error) {
-            console.warn(`Failed to set user data to ${path}:`, error);
-            return false;
-        }
-    }
-    /**
-     * Remove user data at a given path (requires login).
-     * @param path The path to remove data from.
-     * @returns True if successful, false otherwise.
+     * Get direct access to the DataBase instance for full control.
+     * Use this for basic operations like get, put, set, remove, login, etc.
      */
-    async removeUserData(path) {
-        try {
-            if (!this.isLoggedIn()) {
-                console.warn("User not logged in");
-                return false;
-            }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return false;
-            }
-            await this.db.user.get(path).put(null).then();
-            return true;
-        }
-        catch (error) {
-            console.warn(`Failed to remove user data from ${path}:`, error);
-            return false;
-        }
+    get database() {
+        return this.db;
     }
     // =========================
     // Array utilities for GunDB
     // =========================
     /**
      * Convert an array to an indexed object for GunDB storage.
+     * GunDB doesn't store arrays natively, so this converts them to objects indexed by ID.
      * Example: [{id: '1', ...}, {id: '2', ...}] => { "1": {...}, "2": {...} }
-     * @param arr The array to convert.
-     * @returns The indexed object.
-     * @private
+     * @param arr The array to convert (each item must have an 'id' property).
+     * @returns The indexed object suitable for GunDB storage.
      */
-    getIndexedObjectFromArray(arr) {
+    arrayToIndexedObject(arr) {
         // Filter out null/undefined items and ensure they have valid id
         const validItems = (arr || []).filter((item) => item &&
             typeof item === "object" &&
@@ -335,12 +59,12 @@ class SimpleGunAPI {
     }
     /**
      * Convert an indexed object back to an array.
+     * Reverses the arrayToIndexedObject conversion.
      * Example: { "1": {...}, "2": {...} } => [{id: '1', ...}, {id: '2', ...}]
      * @param indexedObj The indexed object to convert.
-     * @returns The array.
-     * @private
+     * @returns The array of items.
      */
-    getArrayFromIndexedObject(indexedObj) {
+    indexedObjectToArray(indexedObj) {
         if (!indexedObj || typeof indexedObj !== "object") {
             return [];
         }
@@ -350,109 +74,17 @@ class SimpleGunAPI {
         // Filter out null/undefined values and ensure they are valid objects
         return Object.values(cleanObj).filter((item) => item && typeof item === "object");
     }
-    /**
-     * Convert an array to an indexed object for GunDB storage (public method).
-     * @param arr The array to convert.
-     * @returns The indexed object.
-     */
-    arrayToIndexedObject(arr) {
-        return this.getIndexedObjectFromArray(arr);
-    }
-    /**
-     * Convert an indexed object to an array (public method).
-     * @param indexedObj The indexed object to convert.
-     * @returns The array.
-     */
-    indexedObjectToArray(indexedObj) {
-        return this.getArrayFromIndexedObject(indexedObj);
-    }
-    // =========================
-    // Path utilities
-    // =========================
-    /**
-     * Get the GunDB user node at a given path (requires login).
-     * Useful for advanced operations that need direct GunDB node access.
-     * @param path The path to the user node.
-     * @returns The Gun node.
-     * @throws If not logged in.
-     */
-    getUserNode(path) {
-        if (!this.isLoggedIn()) {
-            throw new Error("User not logged in");
-        }
-        // Use the database's path deconstruction
-        return this.db.getUser().get(path);
-    }
-    /**
-     * Get the GunDB global node at a given path.
-     * Useful for advanced operations that need direct GunDB node access.
-     * @param path The path to the global node.
-     * @returns The Gun node.
-     */
-    getGlobalNode(path) {
-        // Use the database's path deconstruction
-        return this.db.get(path);
-    }
     // =========================
-    // Quick utility methods
+    // High-level user data helpers
     // =========================
     /**
-     * Get the current user info.
-     * @returns The current user info, or null if not logged in.
+     * Get all user data (returns user's entire data tree).
+     * Requires user to be logged in.
+     * @returns The complete user data tree, or null if not logged in or on error.
      */
-    getCurrentUser() {
-        const user = this.db.getCurrentUser();
-        if (user) {
-            return {
-                pub: user.pub,
-                username: user.alias,
-            };
-        }
-        return null;
-    }
-    /**
-     * Check if a user exists by alias.
-     * @param alias The user alias.
-     * @returns True if the user exists, false otherwise.
-     */
-    async userExists(alias) {
-        try {
-            const user = await this.db.getUserByAlias(alias);
-            return user !== null;
-        }
-        catch (error) {
-            console.warn(`Failed to check if user exists: ${alias}`, error);
-            return false;
-        }
-    }
-    /**
-     * Get user info by alias.
-     * @param alias The user alias.
-     * @returns The user info, or null if not found.
-     */
-    async getUser(alias) {
-        try {
-            const user = await this.db.getUserByAlias(alias);
-            if (user) {
-                return {
-                    userPub: user.userPub,
-                    username: user.username,
-                };
-            }
-            return null;
-        }
-        catch (error) {
-            console.warn(`Failed to get user: ${alias}`, error);
-            return null;
-        }
-    }
-    /**
-     * Advanced user space operations
-     */
-    // Get all user data (returns user's entire data tree)
     async getAllUserData() {
         try {
-            if (!this.isLoggedIn()) {
+            if (!this.db.isLoggedIn()) {
                 console.warn("User not logged in");
                 return null;
             }
@@ -474,18 +106,20 @@ class SimpleGunAPI {
             return null;
         }
     }
-    // Update user profile (common use case) - using direct user node
+    /**
+     * Update user profile with common fields.
+     * Provides a standardized location for user profile data.
+     * @param profileData Profile data to save (name, email, bio, avatar, etc.)
+     * @returns True if successful, false otherwise.
+     */
     async updateProfile(profileData) {
         try {
-            if (!this.isLoggedIn()) {
+            if (!this.db.isLoggedIn()) {
                 console.warn("User not logged in");
                 return false;
             }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return false;
-            }
-            await this.db.user.get("profile").put(profileData).then();
+            const user = this.db.getUser();
+            await user.get("profile").put(profileData).then();
             return true;
         }
         catch (error) {
@@ -493,18 +127,18 @@ class SimpleGunAPI {
             return false;
         }
     }
-    // Get user profile - using direct user node
+    /**
+     * Get user profile data.
+     * @returns The user profile data, or null if not found or not logged in.
+     */
     async getProfile() {
         try {
-            if (!this.isLoggedIn()) {
+            if (!this.db.isLoggedIn()) {
                 console.warn("User not logged in");
                 return null;
             }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return null;
-            }
-            const profileData = await this.db.user.get("profile").once().then();
+            const user = this.db.getUser();
+            const profileData = await user.get("profile").once().then();
             return profileData;
         }
         catch (error) {
@@ -512,18 +146,20 @@ class SimpleGunAPI {
             return null;
         }
     }
-    // Save user settings - using direct user node
+    /**
+     * Save user settings.
+     * Provides a standardized location for application settings.
+     * @param settings Settings object to save.
+     * @returns True if successful, false otherwise.
+     */
     async saveSettings(settings) {
         try {
-            if (!this.isLoggedIn()) {
+            if (!this.db.isLoggedIn()) {
                 console.warn("User not logged in");
                 return false;
             }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return false;
-            }
-            await this.db.user.get("settings").put(settings).then();
+            const user = this.db.getUser();
+            await user.get("settings").put(settings).then();
             return true;
         }
         catch (error) {
@@ -531,18 +167,18 @@ class SimpleGunAPI {
             return false;
         }
     }
-    // Get user settings - using direct user node
+    /**
+     * Get user settings.
+     * @returns The user settings, or null if not found or not logged in.
+     */
     async getSettings() {
         try {
-            if (!this.isLoggedIn()) {
+            if (!this.db.isLoggedIn()) {
                 console.warn("User not logged in");
                 return null;
             }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return null;
-            }
-            const settingsData = await this.db.user.get("settings").once().then();
+            const user = this.db.getUser();
+            const settingsData = await user.get("settings").once().then();
             return settingsData;
         }
         catch (error) {
@@ -550,18 +186,20 @@ class SimpleGunAPI {
             return null;
         }
     }
-    // Save user preferences - using direct user node
+    /**
+     * Save user preferences.
+     * Provides a standardized location for user preferences (distinct from settings).
+     * @param preferences Preferences object to save.
+     * @returns True if successful, false otherwise.
+     */
     async savePreferences(preferences) {
         try {
-            if (!this.isLoggedIn()) {
+            if (!this.db.isLoggedIn()) {
                 console.warn("User not logged in");
                 return false;
             }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return false;
-            }
-            await this.db.user.get("preferences").put(preferences).then();
+            const user = this.db.getUser();
+            await user.get("preferences").put(preferences).then();
             return true;
         }
         catch (error) {
@@ -569,21 +207,18 @@ class SimpleGunAPI {
             return false;
         }
     }
-    // Get user preferences - using direct user node
+    /**
+     * Get user preferences.
+     * @returns The user preferences, or null if not found or not logged in.
+     */
     async getPreferences() {
         try {
-            if (!this.isLoggedIn()) {
+            if (!this.db.isLoggedIn()) {
                 console.warn("User not logged in");
                 return null;
             }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return null;
-            }
-            const preferencesData = await this.db.user
-                .get("preferences")
-                .once()
-                .then();
+            const user = this.db.getUser();
+            const preferencesData = await user.get("preferences").once().then();
             return preferencesData;
         }
         catch (error) {
@@ -591,18 +226,21 @@ class SimpleGunAPI {
             return null;
         }
     }
-    // Create a user collection - using direct user node
+    /**
+     * Create a user collection with initial items.
+     * Provides a standardized location for user collections.
+     * @param collectionName The name of the collection.
+     * @param items The initial items for the collection.
+     * @returns True if successful, false otherwise.
+     */
     async createCollection(collectionName, items) {
         try {
-            if (!this.isLoggedIn()) {
+            if (!this.db.isLoggedIn()) {
                 console.warn("User not logged in");
                 return false;
             }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return false;
-            }
-            await this.db.user.get(`collections/${collectionName}`).put(items).then();
+            const user = this.db.getUser();
+            await user.get(`collections/${collectionName}`).put(items).then();
             return true;
         }
         catch (error) {
@@ -610,18 +248,21 @@ class SimpleGunAPI {
             return false;
         }
     }
-    // Add item to collection - using direct user node
+    /**
+     * Add an item to a user collection.
+     * @param collectionName The name of the collection.
+     * @param itemId The ID of the item to add.
+     * @param item The item data.
+     * @returns True if successful, false otherwise.
+     */
     async addToCollection(collectionName, itemId, item) {
         try {
-            if (!this.isLoggedIn()) {
+            if (!this.db.isLoggedIn()) {
                 console.warn("User not logged in");
                 return false;
             }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return false;
-            }
-            await this.db.user
+            const user = this.db.getUser();
+            await user
                 .get(`collections/${collectionName}/${itemId}`)
                 .put(item)
                 .then();
@@ -632,18 +273,19 @@ class SimpleGunAPI {
             return false;
         }
     }
-    // Get collection - using direct user node
+    /**
+     * Get a user collection.
+     * @param collectionName The name of the collection.
+     * @returns The collection data, or null if not found or not logged in.
+     */
     async getCollection(collectionName) {
         try {
-            if (!this.isLoggedIn()) {
+            if (!this.db.isLoggedIn()) {
                 console.warn("User not logged in");
                 return null;
             }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return null;
-            }
-            const collectionData = await this.db.user
+            const user = this.db.getUser();
+            const collectionData = await user
                 .get(`collections/${collectionName}`)
                 .once()
                 .then();
@@ -654,18 +296,20 @@ class SimpleGunAPI {
             return null;
         }
     }
-    // Remove item from collection - using direct user node
+    /**
+     * Remove an item from a user collection.
+     * @param collectionName The name of the collection.
+     * @param itemId The ID of the item to remove.
+     * @returns True if successful, false otherwise.
+     */
     async removeFromCollection(collectionName, itemId) {
         try {
-            if (!this.isLoggedIn()) {
+            if (!this.db.isLoggedIn()) {
                 console.warn("User not logged in");
                 return false;
             }
-            if (!this.db.user) {
-                console.warn("User node not available");
-                return false;
-            }
-            await this.db.user
+            const user = this.db.getUser();
+            await user
                 .get(`collections/${collectionName}/${itemId}`)
                 .put(null)
                 .then();