From daf23c1c5c8a832ad884b8791850071d1ed7abe7 Mon Sep 17 00:00:00 2001 From: Chneemann Date: Thu, 14 Nov 2024 04:47:27 +0100 Subject: [PATCH] docs: add JSDoc comments to FirebaseService --- src/app/services/firebase.service.ts | 168 +++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) diff --git a/src/app/services/firebase.service.ts b/src/app/services/firebase.service.ts index 0763d2a..ff0f5a9 100644 --- a/src/app/services/firebase.service.ts +++ b/src/app/services/firebase.service.ts @@ -36,6 +36,18 @@ export class FirebaseService implements OnDestroy { // ------------- TASKS ------------- // + /** + * Subscribes to Firestore for the list of all tasks. + * + * This function uses the `onSnapshot` function from `@angular/fire/firestore` to + * subscribe to the 'tasks' collection in Firestore. When the data in the + * collection changes, this function is called with a `QuerySnapshot` object as an + * argument. The function then iterates over the `QuerySnapshot` and creates a + * `Task` object from each document in the snapshot. The created `Task` objects are + * then stored in the `allTasks` array. + * + * @returns The unsubscribe function from `onSnapshot`. + */ subTaskList() { return onSnapshot(collection(this.firestore, 'tasks'), (list) => { this.allTasks = []; @@ -46,14 +58,41 @@ export class FirebaseService implements OnDestroy { }); } + /** + * Returns the list of all tasks. + * + * This function simply returns the value of the `allTasks` property, which is + * an array of `Task` objects that is kept up-to-date by the `subTaskList` + * function. + * + * @returns The list of all tasks. + */ getAllTasks(): Task[] { return this.allTasks; } + /** + * Returns the list of tasks that match the current filter. + * + * This function simply returns the value of the `filteredTasks` property, which + * is an array of `Task` objects that is kept up-to-date by the `searchTask` + * function. + * + * @returns The list of filtered tasks. + */ getFiltertTasks(): Task[] { return this.filteredTasks; } + /** + * Updates the status of a task in the Firestore database. + * + * This function updates the status of the task identified by `taskId` + * using the status from the `allTasks` array at the specified `index`. + * + * @param taskId The ID of the task to be updated. + * @param index The index of the task in the `allTasks` array. + */ async updateTask(taskId: string, index: number) { await updateDoc(doc(collection(this.firestore, 'tasks'), taskId), { status: this.allTasks[index].status, @@ -62,6 +101,16 @@ export class FirebaseService implements OnDestroy { }); } + /** + * Updates the subtasksDone property of a task in the Firestore database. + * + * This function updates the subtasksDone property of the task identified by + * `taskId` with the `array` parameter. The `array` parameter is an array of booleans + * that indicates which subtasks are completed. + * + * @param taskId The ID of the task to be updated. + * @param array An array of booleans that indicates which subtasks are completed. + */ async updateSubTask(taskId: string, array: boolean[]) { await updateDoc(doc(collection(this.firestore, 'tasks'), taskId), { subtasksDone: array, @@ -70,6 +119,17 @@ export class FirebaseService implements OnDestroy { }); } + /** + * Replaces the task identified by `taskId` with the data from the `newData` object. + * + * This function uses the `setDoc` function from `@angular/fire/firestore` to + * replace the task identified by `taskId` with the data from the `newData` object. + * The `newData` object should be of type `Task` and should contain all the fields + * that are required for a task. + * + * @param taskId The ID of the task to be replaced. + * @param newData The new task data. + */ async replaceTaskData(taskId: string, newData: Task) { await setDoc( doc(collection(this.firestore, 'tasks'), taskId), @@ -79,6 +139,14 @@ export class FirebaseService implements OnDestroy { }); } + /** + * Deletes the task with the specified ID from the Firestore database. + * + * This function uses the `deleteDoc` function to remove the task identified by + * `taskId` from the 'tasks' collection in Firestore. + * + * @param taskId The ID of the task to be deleted. + */ async deleteTask(taskId: string) { await deleteDoc(doc(collection(this.firestore, 'tasks'), taskId)).catch( (err) => { @@ -87,6 +155,15 @@ export class FirebaseService implements OnDestroy { ); } + /** + * Adds a new task to the Firestore database. + * + * This function uses the `addDoc` function from `@angular/fire/firestore` to add + * the task to the 'tasks' collection in Firestore. The `task` parameter should be + * of type `Task` and should contain all the fields that are required for a task. + * + * @param task The new task data to be added. + */ async addNewTask(task: Task) { await addDoc(collection(this.firestore, 'tasks'), task).catch((err) => { console.error(err); @@ -95,6 +172,18 @@ export class FirebaseService implements OnDestroy { // ------------- USERS ------------- // + /** + * Subscribes to Firestore for the list of all users. + * + * This function uses the `onSnapshot` function from `@angular/fire/firestore` to + * subscribe to the 'users' collection in Firestore. When the data in the + * collection changes, this function is called with a `QuerySnapshot` object as an + * argument. The function then iterates over the `QuerySnapshot` and creates a + * `User` object from each document in the snapshot. The created `User` objects are + * then stored in the `allUsers` array. + * + * @returns The unsubscribe function from `onSnapshot`. + */ subUserList() { return onSnapshot(collection(this.firestore, 'users'), (list) => { this.allUsers = []; @@ -105,14 +194,30 @@ export class FirebaseService implements OnDestroy { }); } + /** + * Returns the list of all users. + * + * @returns An array of User objects. + */ getAllUsers(): User[] { return this.allUsers; } + /** + * Retrieves a list of all users excluding those with initials 'G' (typically representing guest users). + * + * @returns An array of User objects without guest users. + */ getAllUserWithoutGuest(): User[] { return this.getAllUsers().filter((user) => user.initials !== 'G'); } + /** + * Retrieves a list of all users excluding guest users and the current user and the task creator. + * + * @param taskCreator - The id of the task creator. + * @returns An array of User objects excluding guest users, the current user, and the task creator. + */ getFilteredUsers(taskCreator: string): User[] { const currentUser = this.getCurrentUserId(); const filteredUsers = this.getAllUsers().filter( @@ -121,14 +226,34 @@ export class FirebaseService implements OnDestroy { return filteredUsers.filter((user) => user.id !== taskCreator); } + /** + * Retrieves a list of users from the list of all users that have the given userId. + * + * @param userId - The id of the user to be retrieved. + * @returns An array of User objects with the given userId. + */ getUserDataFromId(userId: string): User[] { return this.getAllUsers().filter((user) => user.id === userId); } + /** + * Retrieves a list of users from the list of all users that have the given userUid. + * + * @param userUid - The unique identifier of the user to be retrieved. + * @returns An array of User objects with the given userUid. + */ getUserDataFromUid(userUid: string): User[] { return this.getAllUsers().filter((user) => user.uId === userUid); } + /** + * Retrieves the current user ID from local storage. + * + * The current user ID is stored in local storage encrypted with the secret key. + * This method decrypts the value and returns the current user ID as a string. + * If the value does not exist or is not decryptable, it returns null. + * @returns The current user ID as a string, or null if not found. + */ getCurrentUserId() { const encryptedValue = localStorage.getItem('currentUserJOIN'); if (encryptedValue) { @@ -139,12 +264,26 @@ export class FirebaseService implements OnDestroy { return null; } + /** + * Retrieves specific user information from the list of all users. + * + * @param userId - The id of the user whose information is to be retrieved. + * @param query - The specific field of the user object to be retrieved, such as 'firstName', 'email', etc. + * @returns An array containing the values of the specified field for the user with the given userId. + */ getUserDetails(userId: string, query: keyof User) { return this.getAllUsers() .filter((user) => user.id === userId) .map((user) => user[query]); } + /** + * Deletes a user document from the Firestore database. + * + * @param docId The id of the document to be deleted. + * @returns A Promise resolving to void. + * @throws An error if the deletion attempt fails. + */ async deleteUser(docId: string) { await deleteDoc(doc(collection(this.firestore, 'users'), docId)).catch( (err) => { @@ -153,6 +292,14 @@ export class FirebaseService implements OnDestroy { ); } + /** + * Updates a user document in the Firestore database. + * + * @param docId The id of the document to be updated. + * @param data The object with the new data to be updated. + * @returns A Promise resolving to void. + * @throws An error if the update attempt fails. + */ async updateUserData(docId: string, data: any) { await updateDoc( doc(collection(this.firestore, 'users'), docId), @@ -162,6 +309,13 @@ export class FirebaseService implements OnDestroy { }); } + /** + * Adds a new user to the Firestore database. + * + * @param userData The data of the user to be added. + * @returns A Promise resolving to the newly added user document. + * @throws An error if the add attempt fails. + */ async addNewUser(userData: User) { try { return await addDoc(collection(this.firestore, 'users'), userData); @@ -173,6 +327,14 @@ export class FirebaseService implements OnDestroy { // ------------- AUTH ------------- // + /** + * Retrieves the current user from local storage. + * + * The current user is stored in local storage encrypted with the secret key. + * This method decrypts the value and returns the current user as an Observable, + * or null if not found. + * @returns An Observable resolving to the current user, or null if not found. + */ getAuthUser(): Observable { const encryptedValue = localStorage.getItem('currentUserJOIN'); if (encryptedValue) { @@ -183,6 +345,12 @@ export class FirebaseService implements OnDestroy { return of(null); } + // ------------- Destroy ------------- // + + /** + * Lifecycle hook that is called when the component is about to be destroyed. + * Unsubscribes from task and user changes to prevent memory leaks. + */ ngOnDestroy() { this.unsubTask(); this.unsubUser();