xonecas.io
53129
Pa

PAT / commit a9a4c48

docs: add JSDoc comments to hooks and library functions

xonecas2025-12-19 a9a4c48b8fe4c8b7c8804d739c2b09df8cb17afb parent 0f2cbc5

8 files changed

src/hooks/useMessages.ts+17−0
@@ -1,6 +1,23 @@
11 import { useState, useEffect, useCallback, useRef } from "react";
22 import type { Message } from "@/src/lib/db/schema";
33
4+/**
5+ * Custom hook for managing messages within a thread.
6+ * Handles loading, sending, streaming, and deleting messages.
7+ *
8+ * @param threadId - The current thread ID or null if no thread is selected
9+ * @param onError - Optional error callback function
10+ * @param onUpdateThreadTitle - Optional callback for updating thread title after first response
11+ * @returns Object containing:
12+ * - `messages` - Array of messages in the current thread
13+ * - `isLoading` - Whether a message is currently being sent/generated
14+ * - `isLoadingMessages` - Whether messages are being loaded from the server
15+ * - `streamingMessageId` - ID of the message currently being streamed, or null
16+ * - `sendMessage` - Function to send a new message
17+ * - `clearMessages` - Function to clear all messages from state
18+ * - `stopGeneration` - Function to stop the current message generation
19+ * - `deleteMessage` - Function to delete a specific message
20+ */
421 export function useMessages(
522 threadId: number | null,
623 onError?: (error: string) => void,
src/hooks/useTheme.ts+8−0
@@ -1,6 +1,14 @@
11 import { useEffect } from "react";
22 import { useLocalStorage } from "./useLocalStorage";
33
4+/**
5+ * Custom hook for managing theme mode (device, dark, or light).
6+ * Automatically applies the theme and listens for system preference changes when in device mode.
7+ *
8+ * @returns Object containing:
9+ * - `themeMode` - Current theme mode: "device", "dark", or "light"
10+ * - `handleThemeChange` - Function to change the theme mode
11+ */
412 export function useTheme() {
513 const [themeMode, setThemeMode] = useLocalStorage<"device" | "dark" | "light">(
614 "themeMode",
src/hooks/useThreadSelection.ts+13−0
@@ -1,5 +1,18 @@
11 import { useState, useEffect, useRef } from "react";
22
3+/**
4+ * Custom hook for managing thread selection state.
5+ * Handles selecting/deselecting threads and automatically scrolls to top when a thread is selected.
6+ *
7+ * @param onThreadSelect - Optional callback function called when a thread is selected
8+ * @param onThreadDeselect - Optional callback function called when a thread is deselected
9+ * @returns Object containing:
10+ * - `currentThreadId` - The currently selected thread ID, or null if none selected
11+ * - `setCurrentThreadId` - Function to directly set the current thread ID
12+ * - `selectThread` - Function to select a thread by ID
13+ * - `deselectThread` - Function to deselect the current thread
14+ * - `messagesContainerRef` - Ref to attach to the messages container element for scrolling
15+ */
316 export function useThreadSelection(
417 onThreadSelect?: (threadId: number) => void,
518 onThreadDeselect?: () => void
src/hooks/useThreads.ts+14−0
@@ -1,6 +1,20 @@
11 import { useState, useEffect } from "react";
22 import type { Thread } from "@/src/lib/db/schema";
33
4+/**
5+ * Custom hook for managing conversation threads.
6+ * Provides state and functions for loading, creating, updating, and deleting threads.
7+ *
8+ * @returns Object containing:
9+ * - `threads` - Array of currently loaded threads
10+ * - `totalThreadCount` - Total number of threads in the database
11+ * - `hasMoreThreads` - Whether there are more threads to load
12+ * - `loadThreads` - Function to load threads with optional limit and error callback
13+ * - `loadMoreThreads` - Function to load additional threads (pagination)
14+ * - `createThread` - Function to create a new thread
15+ * - `updateThread` - Function to update an existing thread
16+ * - `deleteThread` - Function to delete a thread
17+ */
418 export function useThreads() {
519 const [threads, setThreads] = useState<Thread[]>([]);
620 const [totalThreadCount, setTotalThreadCount] = useState<number>(0);
src/lib/db/index.ts+6−1
@@ -18,7 +18,12 @@ const client = postgres(connectionString, {
1818 // Create drizzle instance
1919 export const db = drizzle(client, { schema });
2020
21-// Close database connection (useful for cleanup)
21+/**
22+ * Closes the database connection.
23+ * Useful for cleanup operations, especially in serverless environments.
24+ *
25+ * @returns Promise that resolves when the connection is closed
26+ */
2227 export async function closeDatabase() {
2328 await client.end();
2429 }
src/lib/ollama/chat/abort-handler.ts+4−0
@@ -17,6 +17,10 @@ export function setupAbortHandler(signal: AbortSignal, onAbort: () => void): ()
1717
1818 /**
1919 * Checks if the signal is aborted or if the controller is closed.
20+ *
21+ * @param signal - AbortSignal to check
22+ * @param isClosed - Function that returns whether controller is closed
23+ * @returns Boolean indicating if aborted or closed
2024 */
2125 export function isAbortedOrClosed(signal: AbortSignal, isClosed: () => boolean): boolean {
2226 return signal.aborted || isClosed();
src/lib/ollama/chat/message-persistence.ts+12−0
@@ -10,6 +10,9 @@ import { generateTitle } from "@/src/lib/ollama/title";
1010 /**
1111 * Extracts tool name counts from an array of tool calls.
1212 * Returns a JSON string of the format: {"tool_name": count, ...}
13+ *
14+ * @param toolCalls - Array of tool calls to count
15+ * @returns JSON string of tool name counts, or null if empty
1316 */
1417 export function extractToolCounts(toolCalls: ToolCall[]): string | null {
1518 if (toolCalls.length === 0) return null;
@@ -35,6 +38,15 @@ export interface SaveMessageParams {
3538 /**
3639 * Saves an assistant message to the database and updates the thread's updatedAt timestamp.
3740 * Also generates and updates the thread title from the message history.
41+ *
42+ * @param params - Object containing message data
43+ * @param params.threadId - Thread ID to save message to
44+ * @param params.content - Message content
45+ * @param params.model - Model used for generation
46+ * @param params.maxPromptLength - Max prompt length setting
47+ * @param params.generationTimeMs - Generation time in milliseconds
48+ * @param params.toolCallCounts - JSON string of tool call counts
49+ * @returns Promise that resolves when message is saved
3850 */
3951 export async function saveAssistantMessage(params: SaveMessageParams): Promise<void> {
4052 const { threadId, content, model, maxPromptLength, generationTimeMs, toolCallCounts } = params;
src/lib/ollama/chat/stream-controller.ts+3−0
@@ -3,6 +3,9 @@
33 /**
44 * Creates safe close and enqueue functions for a ReadableStream controller.
55 * These functions prevent double-close errors and handle closed controller states gracefully.
6+ *
7+ * @param controller - The ReadableStream controller to wrap
8+ * @returns Object with `safeClose`, `safeEnqueue`, and `isClosed` functions
69 */
710 export function createStreamController(controller: ReadableStreamDefaultController<Uint8Array>) {
811 let isControllerClosed = false;