shogun-core 5.2.0 → 5.2.2

package/dist/gundb/api.js

@@ -0,0 +1,435 @@
+"use strict";
+/**
+ * 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;
+exports.createSimpleAPI = createSimpleAPI;
+exports.quickStart = quickStart;
+exports.autoQuickStart = autoQuickStart;
+const db_1 = require("./db");
+/**
+ * Simple API wrapper that provides high-level helper methods.
+ * For basic operations, use the DataBase instance directly via the `database` property.
+ */
+class SimpleGunAPI {
+    /**
+     * Create a new SimpleGunAPI instance.
+     * @param db The DataBase instance to use.
+     */
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Get direct access to the DataBase instance for full control.
+     * Use this for basic operations like get, put, set, remove, login, etc.
+     */
+    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 (each item must have an 'id' property).
+     * @returns The indexed object suitable for GunDB storage.
+     */
+    arrayToIndexedObject(arr) {
+        // Filter out null/undefined items and ensure they have valid id
+        const validItems = (arr || []).filter((item) => item &&
+            typeof item === "object" &&
+            item.id !== null &&
+            item.id !== undefined);
+        return validItems.reduce((acc, item) => {
+            return {
+                ...acc,
+                [item.id]: item,
+            };
+        }, {});
+    }
+    /**
+     * 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 of items.
+     */
+    indexedObjectToArray(indexedObj) {
+        if (!indexedObj || typeof indexedObj !== "object") {
+            return [];
+        }
+        // Remove GunDB metadata and convert to array
+        const cleanObj = { ...indexedObj };
+        delete cleanObj._; // Remove GunDB metadata
+        // Filter out null/undefined values and ensure they are valid objects
+        return Object.values(cleanObj).filter((item) => item && typeof item === "object");
+    }
+    /**
+     * @deprecated This method is unreliable with GunDB. Use direct GunDB operations instead.
+     * Store an array at a global path by converting it to an indexed object.
+     * @param path The global path to store the array at
+     * @param arr The array to store (each item must have an 'id' property)
+     * @returns True if successful, false otherwise
+     */
+    async putArray(path, arr) {
+        console.warn("DEPRECATED: putArray() is unreliable with GunDB. Use direct GunDB operations instead.");
+        try {
+            const indexed = this.arrayToIndexedObject(arr);
+            await this.db.put(path, indexed);
+            return true;
+        }
+        catch (error) {
+            console.warn("Failed to put array:", error);
+            return false;
+        }
+    }
+    /**
+     * @deprecated This method is unreliable with GunDB. Use direct GunDB operations instead.
+     * Retrieve an array from a global path by converting from indexed object.
+     * @param path The global path to retrieve the array from
+     * @returns The array of items, or empty array on error
+     */
+    async getArray(path) {
+        console.warn("DEPRECATED: getArray() is unreliable with GunDB. Use direct GunDB operations instead.");
+        try {
+            const indexedObj = await this.db.getData(path);
+            return this.indexedObjectToArray(indexedObj);
+        }
+        catch (error) {
+            console.warn("Failed to get array:", error);
+            return [];
+        }
+    }
+    // =========================
+    // High-level user data helpers
+    // =========================
+    /**
+     * 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.
+     */
+    async getAllUserData() {
+        try {
+            if (!this.db.isLoggedIn()) {
+                console.warn("User not logged in");
+                return null;
+            }
+            const user = this.db.getUser();
+            const pubkey = user.is?.pub;
+            const node = this.db.get(`${pubkey}`);
+            if (node) {
+                const userData = await new Promise((resolve, reject) => {
+                    node.once((data) => {
+                        resolve(data);
+                    });
+                });
+                return userData;
+            }
+            return null;
+        }
+        catch (error) {
+            console.warn("Failed to get all user data:", error);
+            return null;
+        }
+    }
+    /**
+     * 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.db.isLoggedIn()) {
+                console.warn("User not logged in");
+                return false;
+            }
+            const user = this.db.getUser();
+            await user.get("profile").put(profileData).then();
+            return true;
+        }
+        catch (error) {
+            console.warn("Failed to update profile:", error);
+            return false;
+        }
+    }
+    /**
+     * Get user profile data.
+     * @returns The user profile data, or null if not found or not logged in.
+     */
+    async getProfile() {
+        try {
+            if (!this.db.isLoggedIn()) {
+                console.warn("User not logged in");
+                return null;
+            }
+            const user = this.db.getUser();
+            const profileData = await user.get("profile").once().then();
+            return profileData;
+        }
+        catch (error) {
+            console.warn("Failed to get profile:", error);
+            return null;
+        }
+    }
+    /**
+     * 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.db.isLoggedIn()) {
+                console.warn("User not logged in");
+                return false;
+            }
+            const user = this.db.getUser();
+            await user.get("settings").put(settings).then();
+            return true;
+        }
+        catch (error) {
+            console.warn("Failed to save settings:", error);
+            return false;
+        }
+    }
+    /**
+     * Get user settings.
+     * @returns The user settings, or null if not found or not logged in.
+     */
+    async getSettings() {
+        try {
+            if (!this.db.isLoggedIn()) {
+                console.warn("User not logged in");
+                return null;
+            }
+            const user = this.db.getUser();
+            const settingsData = await user.get("settings").once().then();
+            return settingsData;
+        }
+        catch (error) {
+            console.warn("Failed to get settings:", error);
+            return null;
+        }
+    }
+    /**
+     * 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.db.isLoggedIn()) {
+                console.warn("User not logged in");
+                return false;
+            }
+            const user = this.db.getUser();
+            await user.get("preferences").put(preferences).then();
+            return true;
+        }
+        catch (error) {
+            console.warn("Failed to save preferences:", error);
+            return false;
+        }
+    }
+    /**
+     * Get user preferences.
+     * @returns The user preferences, or null if not found or not logged in.
+     */
+    async getPreferences() {
+        try {
+            if (!this.db.isLoggedIn()) {
+                console.warn("User not logged in");
+                return null;
+            }
+            const user = this.db.getUser();
+            const preferencesData = await user.get("preferences").once().then();
+            return preferencesData;
+        }
+        catch (error) {
+            console.warn("Failed to get preferences:", error);
+            return null;
+        }
+    }
+    /**
+     * 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.db.isLoggedIn()) {
+                console.warn("User not logged in");
+                return false;
+            }
+            const user = this.db.getUser();
+            await user.get(`collections/${collectionName}`).put(items).then();
+            return true;
+        }
+        catch (error) {
+            console.warn(`Failed to create collection ${collectionName}:`, error);
+            return false;
+        }
+    }
+    /**
+     * 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.db.isLoggedIn()) {
+                console.warn("User not logged in");
+                return false;
+            }
+            const user = this.db.getUser();
+            await user
+                .get(`collections/${collectionName}/${itemId}`)
+                .put(item)
+                .then();
+            return true;
+        }
+        catch (error) {
+            console.warn(`Failed to add item to collection ${collectionName}:`, error);
+            return false;
+        }
+    }
+    /**
+     * 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.db.isLoggedIn()) {
+                console.warn("User not logged in");
+                return null;
+            }
+            const user = this.db.getUser();
+            const collectionData = await user
+                .get(`collections/${collectionName}`)
+                .once()
+                .then();
+            return collectionData;
+        }
+        catch (error) {
+            console.warn(`Failed to get collection ${collectionName}:`, error);
+            return null;
+        }
+    }
+    /**
+     * 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.db.isLoggedIn()) {
+                console.warn("User not logged in");
+                return false;
+            }
+            const user = this.db.getUser();
+            await user
+                .get(`collections/${collectionName}/${itemId}`)
+                .put(null)
+                .then();
+            return true;
+        }
+        catch (error) {
+            console.warn(`Failed to remove item from collection ${collectionName}:`, error);
+            return false;
+        }
+    }
+}
+exports.SimpleGunAPI = SimpleGunAPI;
+/**
+ * Factory function to create a simple API instance
+ */
+function createSimpleAPI(db) {
+    return new SimpleGunAPI(db);
+}
+/**
+ * Quick start helper - creates a simple API with minimal configuration
+ */
+class QuickStart {
+    constructor(gunInstance, appScope = "shogun") {
+        this.db = new db_1.DataBase(gunInstance, appScope);
+        this.simpleAPI = new SimpleGunAPI(this.db);
+    }
+    // Initialize the database
+    async init() {
+        await this.db.initialize();
+    }
+    // Get the simple API
+    get api() {
+        return this.simpleAPI;
+    }
+    // Get the full database instance for advanced usage
+    get database() {
+        return this.db;
+    }
+}
+exports.QuickStart = QuickStart;
+/**
+ * Auto Quick Start helper - creates a simple API with automatic Gun instance creation
+ * No need to pass a Gun instance, it creates one automatically
+ */
+class AutoQuickStart {
+    constructor(config) {
+        const gunConfig = {
+            peers: config?.peers || [],
+            ...config,
+        };
+        // Remove appScope from gunConfig as it's not a Gun configuration option
+        delete gunConfig.appScope;
+        this.gunInstance = (0, db_1.createGun)(gunConfig);
+        const appScope = config?.appScope || "shogun";
+        this.db = new db_1.DataBase(this.gunInstance, appScope);
+        this.simpleAPI = new SimpleGunAPI(this.db);
+    }
+    // Initialize the database
+    async init() {
+        await this.db.initialize();
+    }
+    // Get the simple API
+    get api() {
+        return this.simpleAPI;
+    }
+    // Get the full database instance for advanced usage
+    get database() {
+        return this.db;
+    }
+    // Get the Gun instance for advanced usage
+    get gun() {
+        return this.gunInstance;
+    }
+}
+exports.AutoQuickStart = AutoQuickStart;
+/**
+ * Global helper for quick setup
+ */
+function quickStart(gunInstance, appScope) {
+    return new QuickStart(gunInstance, appScope);
+}
+/**
+ * Global helper for auto quick setup - creates Gun instance automatically
+ */
+function autoQuickStart(config) {
+    return new AutoQuickStart(config);
+}