shogun-core 6.4.3 → 6.4.4

package/dist/browser/shogun-core.js

@@ -123242,17 +123242,38 @@ var db_generator = (undefined && undefined.__generator) || function (thisArg, bo
 
 
 
+/**
+ * GunDB configuration constants.
+ * @internal
+ */
 var CONFIG = {
     PASSWORD: {
         MIN_LENGTH: 8,
     },
 };
+/**
+ * DataBase
+ *
+ * Manages GunDB user authentication and various utility helpers for
+ * session, alias/username, SEA cryptography, event handling, and reactive streams.
+ */
 var DataBase = /** @class */ (function () {
+    /**
+     * Constructs a new DataBase instance connected to a GunDB instance.
+     * @param gun The main GunDB instance.
+     * @param appScope The namespace under which data/nodes are stored. Default: "shogun"
+     * @param core Optionally, the root Gun instance (unused in this context).
+     * @param sea Optional cryptography (Gun SEA) instance; will be auto-discovered if not provided.
+     * @throws If gun or gun.user() is not provided.
+     */
     function DataBase(gun, appScope, core, sea) {
         if (appScope === void 0) { appScope = "shogun"; }
         var _a;
+        /** Cached user instance or `null` if not logged in */
         this.user = null;
+        /** Registered callbacks for auth state changes */
         this.onAuthCallbacks = [];
+        /** Whether the database instance has been destroyed */
         this._isDestroyed = false;
         this.eventEmitter = new EventEmitter();
         if (!gun) {
@@ -123282,10 +123303,19 @@ var DataBase = /** @class */ (function () {
         this.usernamesNode = this.gun.get("usernames");
         console.log("[DB] DataBase initialization completed");
     }
+    /**
+     * Re-initialize with a different app scope/namespace.
+     * @param appScope The new namespace.
+     */
     DataBase.prototype.initialize = function (appScope) {
         if (appScope === void 0) { appScope = "shogun"; }
         this.node = this.gun.get(appScope);
     };
+    /**
+     * Internal: subscribe to GunDB "auth" events and notify listeners.
+     * Listeners are invoked on authentication status change.
+     * @internal
+     */
     DataBase.prototype.subscribeToAuthEvents = function () {
         var _this = this;
         this.gun.on("auth", function (ack) {
@@ -123298,10 +123328,20 @@ var DataBase = /** @class */ (function () {
             }
         });
     };
+    /**
+     * Internal: notify all onAuth callbacks with current user.
+     * @param pub User's public key (pub).
+     * @internal
+     */
     DataBase.prototype.notifyAuthListeners = function (pub) {
         var user = this.gun.user();
         this.onAuthCallbacks.forEach(function (cb) { return cb(user); });
     };
+    /**
+     * Listen for authentication/sign-in events (login, logout, etc).
+     * @param callback Function to call with new user instance.
+     * @returns Function to remove the registered callback.
+     */
     DataBase.prototype.onAuth = function (callback) {
         var _this = this;
         this.onAuthCallbacks.push(callback);
@@ -123314,6 +123354,10 @@ var DataBase = /** @class */ (function () {
                 _this.onAuthCallbacks.splice(i, 1);
         };
     };
+    /**
+     * Check if a user is currently logged in (there is a valid session).
+     * @returns `true` if logged in; otherwise `false`.
+     */
     DataBase.prototype.isLoggedIn = function () {
         try {
             var user = this.gun.user();
@@ -123323,6 +123367,10 @@ var DataBase = /** @class */ (function () {
             return false;
         }
     };
+    /**
+     * Attempt to restore a previously saved session from sessionStorage.
+     * @returns Object indicating success, error, and userPub if restored.
+     */
     DataBase.prototype.restoreSession = function () {
         try {
             if (typeof sessionStorage === "undefined") {
@@ -123353,6 +123401,9 @@ var DataBase = /** @class */ (function () {
             return { success: false, error: String(error) };
         }
     };
+    /**
+     * Log out the current user, clear local state and remove session from storage.
+     */
     DataBase.prototype.logout = function () {
         try {
             var currentUser = this.gun.user();
@@ -123368,6 +123419,11 @@ var DataBase = /** @class */ (function () {
             console.error("[DB] Error during logout:", error);
         }
     };
+    /**
+     * Validate that a provided password meets minimum length requirements.
+     * @param password Password string to validate.
+     * @returns Object indicating validity and, if invalid, an error.
+     */
     DataBase.prototype.validatePasswordStrength = function (password) {
         if (password.length < CONFIG.PASSWORD.MIN_LENGTH) {
             return {
@@ -123377,6 +123433,13 @@ var DataBase = /** @class */ (function () {
         }
         return { valid: true };
     };
+    /**
+     * Validate a signup request's username, password, and/or cryptographic pair.
+     * @param username Username string.
+     * @param password Password string.
+     * @param pair Optional cryptographic SEA pair.
+     * @returns Object with validation status and optional error.
+     */
     DataBase.prototype.validateSignupCredentials = function (username, password, pair) {
         if (!username || username.length < 1) {
             return {
@@ -123398,6 +123461,12 @@ var DataBase = /** @class */ (function () {
         }
         return this.validatePasswordStrength(password);
     };
+    /**
+     * Ensures that an alias/username is available in GunDB for registration.
+     * @param alias Username to check.
+     * @param timeout Timeout in milliseconds (default 5000ms).
+     * @throws If the alias is already taken.
+     */
     DataBase.prototype.ensureAliasAvailable = function (alias_1) {
         return db_awaiter(this, arguments, void 0, function (alias, timeout) {
             var available;
@@ -123415,6 +123484,13 @@ var DataBase = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Checks if a given alias/username is available on GunDB.
+     * @param alias Username to check for availability.
+     * @param timeout Timeout in ms (default: 5000).
+     * @returns Promise resolving to `true` if available; otherwise `false`.
+     * @throws If alias is invalid or on I/O error.
+     */
     DataBase.prototype.isAliasAvailable = function (alias_1) {
         return db_awaiter(this, arguments, void 0, function (alias, timeout) {
             var normalizedAlias;
@@ -123444,9 +123520,39 @@ var DataBase = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Checks if a given alias/username is taken on GunDB.
+     * @param alias Username to check for availability.
+     * @returns Promise resolving to `true` if taken; otherwise `false`.
+     * @throws If alias is invalid or on I/O error.
+     */
+    DataBase.prototype.isAliasTaken = function (alias) {
+        return db_awaiter(this, void 0, void 0, function () {
+            var _this = this;
+            return db_generator(this, function (_a) {
+                return [2 /*return*/, new Promise(function (resolve, reject) {
+                        _this.gun.get("~@".concat(alias)).once(function (user) {
+                            if (user) {
+                                resolve(false);
+                            }
+                            else {
+                                resolve(true);
+                            }
+                        });
+                    })];
+            });
+        });
+    };
+    /**
+     * Register a new alias (username) → public key mapping on GunDB.
+     * @param alias The username/alias to register.
+     * @param userPub The user's public key.
+     * @param timeout Timeout in ms (default 5000).
+     * @throws If alias/userPub is invalid or the alias cannot be registered.
+     */
     DataBase.prototype.registerAlias = function (alias_1, userPub_1) {
         return db_awaiter(this, arguments, void 0, function (alias, userPub, timeout) {
-            var normalizedAlias, available;
+            var normalizedAlias, available, taken;
             var _this = this;
             if (timeout === void 0) { timeout = 5000; }
             return db_generator(this, function (_a) {
@@ -123465,6 +123571,12 @@ var DataBase = /** @class */ (function () {
                             })];
                     case 1:
                         available = _a.sent();
+                        return [4 /*yield*/, this.isAliasTaken(normalizedAlias)];
+                    case 2:
+                        taken = _a.sent();
+                        if (taken) {
+                            throw new Error("Alias \"".concat(normalizedAlias, "\" is already taken"));
+                        }
                         if (!available) {
                             throw new Error("Alias \"".concat(normalizedAlias, "\" is no longer available for registration"));
                         }
@@ -123491,13 +123603,17 @@ var DataBase = /** @class */ (function () {
                                 console.error("[DB] Failed to register alias:", error);
                                 throw error;
                             })];
-                    case 2:
+                    case 3:
                         _a.sent();
                         return [2 /*return*/];
                 }
             });
         });
     };
+    /**
+     * Reset gun.user() authentication state and clear cached user.
+     * @internal
+     */
     DataBase.prototype.resetAuthState = function () {
         try {
             var user = this.gun.user();
@@ -123522,6 +123638,13 @@ var DataBase = /** @class */ (function () {
             // Ignore
         }
     };
+    /**
+     * Assemble a standard AuthResult object after a successful login.
+     * @param username Resulting username.
+     * @param userPub Public key (pub) for logged-in user.
+     * @returns AuthResult.
+     * @internal
+     */
     DataBase.prototype.buildLoginResult = function (username, userPub) {
         var _a, _b;
         var seaPair = (_b = (_a = this.gun.user()) === null || _a === void 0 ? void 0 : _a._) === null || _b === void 0 ? void 0 : _b.sea;
@@ -123539,6 +123662,10 @@ var DataBase = /** @class */ (function () {
                 : undefined,
         };
     };
+    /**
+     * Save credentials for the current session to sessionStorage, if available.
+     * @param userInfo The credentials and user identity to store.
+     */
     DataBase.prototype.saveCredentials = function (userInfo) {
         try {
             if (typeof sessionStorage !== "undefined") {
@@ -123556,6 +123683,13 @@ var DataBase = /** @class */ (function () {
             console.error("[DB] Error saving credentials:", error);
         }
     };
+    /**
+     * Register and authenticate a new user account.
+     * @param username The username to create/account for.
+     * @param password The user's password.
+     * @param pair Optional cryptographic pair (for `auth` instead of password).
+     * @returns SignUpResult Promise.
+     */
     DataBase.prototype.signUp = function (username, password, pair) {
         return db_awaiter(this, void 0, void 0, function () {
             var validation, normalizedUsername, user, loginResult, e_1, aliasError_1, result;
@@ -123727,6 +123861,13 @@ var DataBase = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Sign in (authenticate) as an existing user by username/password or SEA pair.
+     * @param username Username to log in as.
+     * @param password User's password (or "" if using pair).
+     * @param pair Optional cryptographic SEA pair.
+     * @returns AuthResult Promise.
+     */
     DataBase.prototype.login = function (username, password, pair) {
         return db_awaiter(this, void 0, void 0, function () {
             var normalizedUsername, user;
@@ -123800,6 +123941,10 @@ var DataBase = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Returns the currently authenticated user's public key and Gun user instance, if logged in.
+     * @returns Object containing `pub` (public key) and optionally `user`, or `null`.
+     */
     DataBase.prototype.getCurrentUser = function () {
         try {
             var user = this.gun.user();
@@ -123816,8 +123961,8 @@ var DataBase = /** @class */ (function () {
         }
     };
     /**
-     * Get current user's public key
-     * @returns {string | null} User's public key or null if not logged in
+     * Get current user's public key.
+     * @returns User's public key or null if not logged in.
      */
     DataBase.prototype.getUserPub = function () {
         var _a;
@@ -123830,11 +123975,11 @@ var DataBase = /** @class */ (function () {
         }
     };
     /**
-     * Login with SEA pair directly
-     * @param username - Username for identification
-     * @param pair - GunDB SEA pair for authentication
-     * @returns {Promise<AuthResult>} Promise with authentication result
-     * @description Authenticates user using a GunDB pair directly without password
+     * Authenticate using a SEA pair directly (no password required).
+     * @param username The user's username for identification (not cryptographically enforced).
+     * @param pair GunDB SEA pair for authentication.
+     * @returns Promise with authentication result.
+     * @description Authenticates user using a GunDB pair directly without password.
      */
     DataBase.prototype.loginWithPair = function (username, pair) {
         return db_awaiter(this, void 0, void 0, function () {
@@ -123885,6 +124030,12 @@ var DataBase = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Legacy API: Sign in using a username and SEA pair (password parameter is unused).
+     * @param username Username to sign in as.
+     * @param pair SEA key pair.
+     * @returns AuthResult Promise.
+     */
     DataBase.prototype.loginWithPairLegacy = function (username, pair) {
         return db_awaiter(this, void 0, void 0, function () {
             return db_generator(this, function (_a) {
@@ -123892,9 +124043,17 @@ var DataBase = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Returns the bound RxJS GunDB helper (reactive streams).
+     * @returns RxJS instance.
+     */
     DataBase.prototype.rx = function () {
         return this._rxjs;
     };
+    /**
+     * Tears down the DataBase instance and performs cleanup of all resources/listeners.
+     * No further actions should be performed on this instance after destruction.
+     */
     DataBase.prototype.destroy = function () {
         if (this._isDestroyed)
             return;
@@ -123914,21 +124073,45 @@ var DataBase = /** @class */ (function () {
         this._rxjs = undefined;
         console.log("[DB] DataBase instance destroyed");
     };
+    /**
+     * Aggressively clean up authentication state and session. Typically used for error recovery.
+     */
     DataBase.prototype.aggressiveAuthCleanup = function () {
         console.log("🧹 Performing aggressive auth cleanup...");
         this.resetAuthState();
         this.logout();
         console.log("✓ Aggressive auth cleanup completed");
     };
+    /**
+     * Register an event handler.
+     * @param event Event name.
+     * @param listener Listener function.
+     */
     DataBase.prototype.on = function (event, listener) {
         this.eventEmitter.on(event, listener);
     };
+    /**
+     * Remove an event handler.
+     * @param event Event name.
+     * @param listener Listener function.
+     */
     DataBase.prototype.off = function (event, listener) {
         this.eventEmitter.off(event, listener);
     };
+    /**
+     * Register an event handler for a single event occurrence.
+     * @param event Event name.
+     * @param listener Listener function.
+     */
     DataBase.prototype.once = function (event, listener) {
         this.eventEmitter.once(event, listener);
     };
+    /**
+     * Emit a custom event.
+     * @param event Event name.
+     * @param data Optional associated data.
+     * @returns `true` if listeners were notified; otherwise `false`.
+     */
     DataBase.prototype.emit = function (event, data) {
         return this.eventEmitter.emit(event, data);
     };