From a6b3ab15ccdfa8f44154c55058400c981b642ad9 Mon Sep 17 00:00:00 2001
From: themodrnhakr <ehrumsey@gmail.com>
Date: Sat, 4 Oct 2025 00:33:31 -0500
Subject: [PATCH] Add documentation.

---
 src/lib/server/services/tasks.ts | 41 ++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/src/lib/server/services/tasks.ts b/src/lib/server/services/tasks.ts
index 284f230..f1d423e 100644
--- a/src/lib/server/services/tasks.ts
+++ b/src/lib/server/services/tasks.ts
@@ -14,15 +14,32 @@ export type TaskOrNull = InferSelectModel<typeof tasks> & {
 
 export type NewTask = typeof tasks.$inferInsert;
 
+/**
+ * Service for interacting with `Task` records.
+ * @method `getAll`
+ * @method `getByDbId`
+ * @method `getByTaskId`
+ * @method `getByParent`
+ * @method `upsert`
+ */
 class TasksService {
   private db: DB;
   private caller: "internal" | "api";
 
+  /**
+   * @param caller - The domain of the service consumer. Aids in domain-related security and logging.
+   * @param dbClient - drizzle database client.
+   */
   constructor(caller: "internal" | "api", dbClient: DB = db) {
     this.db = dbClient;
     this.caller = caller;
   }
 
+  /**
+   * Private method for safe database querying.
+   * @param query - Takes a drizzle query.
+   * @returns A `ServiceResponse` Promise. On success, `data` is an array of tasks.
+   */
   private async _executeQuery(
     query: () => Promise<TaskOrNull[]>,
   ): Promise<ServiceResponse<Task[], "INTERNAL_ERROR" | "DATA_INTEGRITY_VIOLATION">> {
@@ -45,11 +62,20 @@ class TasksService {
     }
   }
 
+  /**
+   * Fetch all tasks.
+   * @returns An array of all task records with relations included.
+   */
   public async getAll() {
     logger.info("Fetching all task records...");
     return this._executeQuery(() => this.db.query.tasks.findMany({ with: { type: true } }));
   }
 
+  /**
+   * Request tasks by `type.prefix` + `task_id` strings. Allows for some additional checks based on expected task type.
+   * @param taskIds - An array of `type.prefix` + `task_id` strings.
+   * @returns A `ServiceResponse` object. On success, `data` is an array of tasks.
+   */
   public async getByTaskId(taskIds: Array<string>) {
     const mappedTasks = taskIds.map(x => {
       const prefix = x.slice(0, 2);
@@ -73,6 +99,11 @@ class TasksService {
     );
   }
 
+  /**
+   * Request tasks by `id` field.
+   * @param ids - An array of `id`s.
+   * @returns A `ServiceResponse` object. On success, `data` is an array of tasks.
+   */
   public async getByDbId(ids: Array<number>) {
     logger.info(`Fetching ${ids.length} records.`);
     return this._executeQuery(() =>
@@ -83,6 +114,11 @@ class TasksService {
     );
   }
 
+  /**
+   * Request all child tasks. Tasks are looked up by `parent`.
+   * @param id - A single task `id`.
+   * @returns A `ServiceResponse` object. On success, `data` is an array of tasks.
+   */
   public async getByParent(id: NonNullable<Task["id"]>) {
     logger.info(`Searching for records with parent '${id}'.`);
     return this._executeQuery(() =>
@@ -93,6 +129,11 @@ class TasksService {
     );
   }
 
+  /**
+   * Checks for the presence of an `id` field. If the field exists, an update action is attempted. If `id` does not exist, and insertion action is attempted.
+   * @param taskData - Data for record update or insertion.
+   * @returns A `ServiceResponse` object. On success, `data` is the updated/inserted task's `id`.
+   */
   public async upsert(
     taskData: NewTask,
   ): Promise<ServiceResponse<{ id: number }, "INTERNAL_ERROR" | "MISSING_DATABASE_ENTRY" | "RECORD_CREATION_FAILURE">> {