diff --git a/src/db/services/database.ts b/src/db/services/database.ts index 79cf407..3963706 100644 --- a/src/db/services/database.ts +++ b/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. - * @throws Will throw an error if the database cannot be initialized. + * @example + * const db = await DatabaseService.getDatabase(); + * + * @returns {Promise} 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 { const databaseInitializer = DatabaseInitializer.getInstance(); @@ -25,11 +28,20 @@ export class DatabaseService { /** * Inserts a new comment into the database. - * - * This method constructs an SQL statement to insert all fields of the Comment object + * This static 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 { 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. - * It uses `getDatabase` method internally to ensure that database operations - * are performed on the same database instance throughout the application. + * This static method adds a record of a user being mentioned in a comment. * - * @param mention - The user mention object to insert. It must include: - * - rdrama_comment_id: The ID of the comment from the r/Drama platform. - * - username: The mentioned Reddit username in a standardized format (e.g., u/username). - * - message: (Optional) The content of the message sent to the mentioned user. + * @example + * await DatabaseService.insertUserMention({ + * rdrama_comment_id: 456, + * 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 { 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} 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 { 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} 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 { const db = await DatabaseService.getDatabase() @@ -99,11 +123,13 @@ export class DatabaseService { } /** - * Retrieves the last run timestamp for a specified maintenance task. - * This method queries the `maintenance_log` table to find the last time a specific task was run. + * Updates the last run timestamp for a maintenance task, using an "upsert" approach. * - * @param {string} taskName - The name of the maintenance task for which to retrieve the last run timestamp. - * @returns {Promise} A promise that resolves to the Date of the last run if found, or null if not found. + * @example + * 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 { 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. - * 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. + * Updates the last run timestamp for a maintenance task, using an "upsert" approach. * - * @param {string} taskName - The name of the maintenance task for which to update the last run timestamp. - * @returns {Promise} A promise that resolves when the operation is complete. + * @example + * 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 { // 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. - * This method is intended to be run as part of periodic maintenance tasks to keep the database size manageable. + * Deletes comments from the database older than a specified number of days. * - * @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 { 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. - * @param {Object} tokenData - The OAuth token data. + * @example + * 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. - * @param {string} token_identifier - The baseurl for the axios instance. + * Retrieves the current, unexpired OAuth token for a specific service. + * + * @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} 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} 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} 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 { const db = await DatabaseService.getDatabase() @@ -219,5 +268,4 @@ export class DatabaseService { return timeElapsed >= cooldownPeriod; } - }