J
/
OregonTrail
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Minor Formatting, Commented all methods

master
sloppyjosh 2024-03-07 02:04:34 -05:00
parent 28e280556e
commit f80ef1005d
1 changed files with 86 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
src/db/services/database.ts
View File

@ -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<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 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<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.
* 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<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.
* 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<Date | null>} 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<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.
* 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<void>} 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<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.
* 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<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.
* @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<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;
}
}