Minor Formatting, Commented all methods

src/db/services/database.ts

@@ -8,11 +8,14 @@ import { DatabaseInitializer } from '../initializeDatabase';
 export class DatabaseService {
     /**
      * Retrieves the singleton instance of the database.
-     * This method ensures that a single database instance is used throughout the application,
+     * This static method ensures that a single database instance is used throughout the application,
      * following the singleton pattern for managing database connections.
      * 
-     * @returns A promise that resolves to the initialized database instance.
+     * @example
-     * @throws Will throw an error if the database cannot be initialized.
+     * const db = await DatabaseService.getDatabase();
+     * 
+     * @returns {Promise<Database>} A promise that resolves to the initialized database instance.
+     * @throws {Error} Will throw an error if the database cannot be initialized.
      */
     private static async getDatabase(): Promise<Database> {
         const databaseInitializer = DatabaseInitializer.getInstance();
@@ -25,11 +28,20 @@ export class DatabaseService {
 
     /**
      * Inserts a new comment into the database.
-     * 
+     * This static method constructs an SQL statement to insert all fields of the Comment object
-     * This method constructs an SQL statement to insert all fields of the Comment object
      * into the corresponding columns in the 'comments' table.
      * 
+     * @example
+     * await DatabaseService.insertComment({
+     *   id: 1,
+     *   author_id: 123,
+     *   author_name: 'exampleUser',
+     *   body: 'This is a comment.',
+     *   // More fields as per the Comment type
+     * });
+     * 
      * @param {Comment} comment - The comment object to insert.
+     * @throws {Error} Will throw an error if the insert operation fails.
      */
     public static async insertComment(comment: Comment): Promise<void> {
         const db = await DatabaseService.getDatabase()
@@ -53,16 +65,20 @@ export class DatabaseService {
 
     /**
      * Inserts a new user mention into the database.
-     * This method is static and can be called without creating an instance of the class.
+     * This static method adds a record of a user being mentioned in a comment.
-     * It uses `getDatabase` method internally to ensure that database operations
-     * are performed on the same database instance throughout the application.
      * 
-     * @param mention - The user mention object to insert. It must include:
+     * @example
-     *  - rdrama_comment_id: The ID of the comment from the r/Drama platform.
+     * await DatabaseService.insertUserMention({
-     *  - username: The mentioned Reddit username in a standardized format (e.g., u/username).
+     *   rdrama_comment_id: 456,
-     *  - message: (Optional) The content of the message sent to the mentioned user.
+     *   username: 'mentionedUser',
+     *   message: 'You were mentioned in a comment.'
+     * });
      * 
-     * @throws Will throw an error if the database cannot be initialized or the insert operation fails.
+     * @param {Object} mention - The user mention object to insert.
+     * @param {number} mention.rdrama_comment_id - The ID of the comment from the r/Drama platform.
+     * @param {string} mention.username - The mentioned Reddit username.
+     * @param {string} [mention.message] - The content of the message sent to the mentioned user.
+     * @throws {Error} Will throw an error if the insert operation fails.
      */
     public static async insertUserMention(mention: { rdrama_comment_id: number; username: string; message?: string }): Promise<void> {
         const db = await DatabaseService.getDatabase()
@@ -70,13 +86,16 @@ export class DatabaseService {
         await db.run(sql, [mention.rdrama_comment_id, mention.username, mention.message]);
     }
 
-
-
     /**
-     * Queries the database for an existing comment.
+     * Queries the database for an existing comment by its ID.
+     * 
+     * @example
+     * const exists = await DatabaseService.commentExists('123');
+     * console.log(exists ? 'Comment exists.' : 'Comment does not exist.');
      * 
      * @param {string} commentId - The ID of the comment to search for.
      * @returns {Promise<boolean>} A boolean indicating whether the comment exists.
+     * @throws {Error} Will throw an error if the query operation fails.
      */
     public static async commentExists(commentId: string): Promise<boolean> {
         const db = await DatabaseService.getDatabase()
@@ -86,10 +105,15 @@ export class DatabaseService {
     }
 
     /**
-     * Queries the database for existing mentions of a username.
+     * Queries the database to check if a username has been mentioned.
+     * 
+     * @example
+     * const mentioned = await DatabaseService.userMentionExists('exampleUser');
+     * console.log(mentioned ? 'User has been mentioned.' : 'User has not been mentioned.');
      * 
      * @param {string} username - The username to search for.
      * @returns {Promise<boolean>} A boolean indicating whether the username has been mentioned.
+     * @throws {Error} Will throw an error if the query operation fails.
      */
     public static async userMentionExists(username: string): Promise<boolean> {
         const db = await DatabaseService.getDatabase()
@@ -99,11 +123,13 @@ export class DatabaseService {
     }
 
     /**
-     * Retrieves the last run timestamp for a specified maintenance task.
+     * Updates the last run timestamp for a maintenance task, using an "upsert" approach.
-     * This method queries the `maintenance_log` table to find the last time a specific task was run.
      * 
-     * @param {string} taskName - The name of the maintenance task for which to retrieve the last run timestamp.
+     * @example
-     * @returns {Promise<Date | null>} A promise that resolves to the Date of the last run if found, or null if not found.
+     * await DatabaseService.updateLastRunTimestamp('purgeOldComments');
+     * 
+     * @param {string} taskName - The name of the maintenance task.
+     * @throws {Error} Will throw an error if the update operation fails.
      */
     public static async getLastRunTimestamp(taskName: string): Promise<Date | null> {
         const db = await DatabaseService.getDatabase()
@@ -112,13 +138,13 @@ export class DatabaseService {
     }
 
     /**
-     * Updates the last run timestamp for a specific maintenance task in the `maintenance_log` table.
+     * Updates the last run timestamp for a maintenance task, using an "upsert" approach.
-     * This method uses an "upsert" approach, which inserts a new record if one doesn't exist for the task,
-     * or updates the existing record if it does. This ensures that each task has only one record in the table
-     * reflecting its most recent execution time.
      * 
-     * @param {string} taskName - The name of the maintenance task for which to update the last run timestamp.
+     * @example
-     * @returns {Promise<void>} A promise that resolves when the operation is complete.
+     * await DatabaseService.updateLastRunTimestamp('purgeOldComments');
+     * 
+     * @param {string} taskName - The name of the maintenance task.
+     * @throws {Error} Will throw an error if the update operation fails.
      */
     public static async updateLastRunTimestamp(taskName: string): Promise<void> {
         // Assumes an "upsert" approach for the maintenance_log table
@@ -133,10 +159,13 @@ export class DatabaseService {
     }
 
     /**
-     * Deletes comments from the database that are older than a specified number of days.
+     * Deletes comments from the database older than a specified number of days.
-     * This method is intended to be run as part of periodic maintenance tasks to keep the database size manageable.
      * 
-     * @param {number} [days=1] - The age of comments to be purged, in days. Defaults to 30 days.
+     * @example
+     * await DatabaseService.purgeOldComments(30); // Purge comments older than 30 days
+     * 
+     * @param {number} days - The age of comments to be purged, in days.
+     * @throws {Error} Will throw an error if the purge operation fails.
      */
     public static async purgeOldComments(days: number = 1): Promise<void> {
         const db = await DatabaseService.getDatabase()
@@ -148,10 +177,19 @@ export class DatabaseService {
     }
 
     /**
-     * Inserts or updates the OAuth token in the database.
+     * Inserts or updates the OAuth token in the database for a specific service.
      * 
-     * @param {string} token_identifier - The baseurl for the axios instance.
+     * @example
-     * @param {Object} tokenData - The OAuth token data.
+     * await DatabaseService.upsertOAuthToken('https://oauth.reddit.com', {
+     *   access_token: 'abc123',
+     *   token_type: 'bearer',
+     *   expires_in: 3600,
+     *   scope: 'read'
+     * });
+     * 
+     * @param {string} token_identifier - A unique identifier for the token, typically the service's base URL.
+     * @param {Object} tokenData - The OAuth token data including access_token, token_type, expires_in, and scope.
+     * @throws {Error} Will throw an error if the upsert operation fails.
      */
     public static async upsertOAuthToken(token_identifier: string, tokenData: any) {
         const db = await DatabaseService.getDatabase()
@@ -176,9 +214,15 @@ export class DatabaseService {
     }
 
     /**
-     * Retrieves the current OAuth token.
+     * Retrieves the current, unexpired OAuth token for a specific service.
-     * @param {string} token_identifier - The baseurl for the axios instance.
+     * 
+     * @example
+     * const token = await DatabaseService.getCurrentOAuthToken('https://oauth.reddit.com');
+     * console.log(token ? `Current token: ${token.access_token}` : 'No valid token found.');
+     * 
+     * @param {string} token_identifier - The unique identifier for the token, typically the service's base URL.
      * @returns {Promise<Object|null>} The current OAuth token data or null if expired or not found.
+     * @throws {Error} Will throw an error if the query operation fails.
      */
     public static async getCurrentOAuthToken(token_identifier: string) {
         const db = await DatabaseService.getDatabase()
@@ -191,9 +235,14 @@ export class DatabaseService {
     }
 
     /**
-     * Checks if the cooldown period has passed since the last notification was sent to any user.
+     * Checks if the cooldown period has passed since the last notification was sent, allowing for a new notification to be sent.
      * 
-     * @returns {Promise<boolean>} True if the cooldown has passed, allowing new notifications to be sent.
+     * @example
+     * const canSend = await DatabaseService.canSendNotification();
+     * console.log(canSend ? 'Can send a new notification.' : 'Still in cooldown period.');
+     * 
+     * @returns {Promise<boolean>} True if the cooldown period has passed, allowing new notifications to be sent.
+     * @throws {Error} Will throw an error if the check operation fails.
      */
     public static async canSendNotification(): Promise<boolean> {
         const db = await DatabaseService.getDatabase()
@@ -219,5 +268,4 @@ export class DatabaseService {
         return timeElapsed >= cooldownPeriod;
     }
 
-
 }