utils.ts

Overview

The utils.ts file provides a collection of utility functions that facilitate handling and processing chat conversation data within the application. These utilities primarily focus on validating conversation identifiers, extracting document IDs from conversation references, building message reference objects, and normalizing text patterns used for indexing and referencing documents in chat messages.

These helpers abstract common operations performed on chat conversation and message data structures, ensuring consistency and reusability across the application’s chat-related modules.

Functions

1. isConversationIdExist

export const isConversationIdExist = (conversationId: string) => boolean;

Purpose:
Checks whether a given conversation ID is valid and exists by confirming it is neither empty nor equal to a predefined empty conversation ID constant.

Parameters:

• conversationId (string): The conversation ID to validate.

Returns:

• boolean: true if the conversation ID is considered existing/valid; otherwise, false.

Usage Example:

import { isConversationIdExist } from './utils';

const valid = isConversationIdExist('abc123'); // true or false

2. getDocumentIdsFromConversionReference

export const getDocumentIdsFromConversionReference = (data: IConversation) => string;

Purpose:
Extracts all unique document IDs referenced within a conversation's references and returns them as a comma-separated string.

Parameters:

• data (IConversation): The conversation object containing a reference array. Each reference may include multiple document aggregations (doc_aggs) with document IDs.

Returns:

• string: A comma-separated list of unique document IDs extracted from the conversation's references.

Implementation Details:

• Iterates over each IReference in the conversation's reference array.

• Extracts doc_id from nested doc_aggs.

• Collects unique document IDs to avoid duplicates.

• Joins the collected IDs into a single comma-separated string.

Usage Example:

import { getDocumentIdsFromConversionReference } from './utils';

const docIds = getDocumentIdsFromConversionReference(conversationObj);
console.log(docIds); // "doc1,doc2,doc3"

3. buildMessageItemReference

export const buildMessageItemReference = (
  conversation: { message: IMessage[]; reference: IReference[] },
  message: IMessage
) => IReference;

Purpose:
Constructs or retrieves the appropriate reference object associated with a specific chat message within a conversation.

Parameters:

• conversation ({ message: IMessage[]; reference: IReference[] }):
  An object containing arrays of messages and references linked to the conversation.

• message (IMessage):
  The message for which the reference needs to be resolved.

Returns:

• IReference:
  The reference object corresponding to the message. If no reference is found on the message itself, it attempts to find the corresponding reference by matching the message ID among assistant messages (excluding the first one). Returns a default empty reference object if none is found.

Implementation Details:

• Filters assistant role messages starting from the second assistant message.

• Finds the index of the message whose ID matches the target message ID.

• Uses this index to retrieve the corresponding reference from the conversation references.

• Falls back to the message's own reference if present.

• Returns a default empty reference if none found.

Usage Example:

import { buildMessageItemReference } from './utils';

const ref = buildMessageItemReference(conversation, message);
console.log(ref.doc_aggs);

4. replaceTextByOldReg

export const replaceTextByOldReg = (text: string) => string;

Purpose:
Normalizes legacy indexed text patterns to the current format used for document referencing.

Parameters:

• text (string):
  The text string containing old index patterns (like ##123$$).

Returns:

• string:
  The input text with all old index patterns replaced by the new format [ID:123].

Implementation Details:

• Uses a regular expression oldReg to find all occurrences of the old pattern ##<digits>$$.

• Replaces each match with the new pattern [ID:<digits>].

Related Constant:

• oldReg: Regular expression to detect old index format.

• currentReg: Regular expression for current index format [ID:<digits>].

Usage Example:

import { replaceTextByOldReg } from './utils';

const normalizedText = replaceTextByOldReg("Reference ##123$$ here");
console.log(normalizedText); // "Reference [ID:123] here"

Important Implementation Details

• Uniqueness Filtering:
  In getDocumentIdsFromConversionReference, uniqueness of document IDs is ensured by checking that the ID is not already in the accumulator array before pushing it.

• Message-Reference Matching:
  The buildMessageItemReference function relies on a positional mapping between assistant messages (excluding the first) and references. This assumes references align sequentially with assistant messages for proper matching.

• Backward Compatibility:
  The replaceTextByOldReg function supports compatibility with legacy text indexing formats, enabling smooth migration or coexistence of old and new reference styles.

Interaction with Other Parts of the System

• Constants:
  Uses EmptyConversationId and MessageType from the @/constants/chat module to validate conversation IDs and filter messages by role.

• Interfaces:
  Relies on IConversation and IReference interfaces from @/interfaces/database/chat and IMessage from ../chat/interface to ensure type safety and consistent data structures.

• External Libraries:
  Uses isEmpty from lodash to check if message references are empty when building references.

• Usage Context:
  These utilities are intended to be used in chat-related components or services for validating conversations, extracting referenced documents, and preparing message data for rendering or processing.

Visual Diagram

flowchart TD
    A[isConversationIdExist] -->|Validates| B[Conversation ID]

    subgraph Extract Document IDs
        C[getDocumentIdsFromConversionReference]
        C -->|Iterate references| D[References]
        D --> E[doc_aggs]
        E --> F[doc_id]
        F --> G[Unique doc IDs]
        G --> H[Comma-separated string]
    end

    subgraph Build Message Reference
        I[buildMessageItemReference]
        I -->|Input| J[Conversation: messages & references]
        I -->|Input| K[Message]
        J --> L[Assistant messages (excluding first)]
        L --> M[Find index of message]
        M --> N[Select reference by index]
        K -->|Check message.reference| O[Use message reference if present]
        N & O --> P[Resulting reference or default]
    end

    subgraph Text Replacement
        Q[replaceTextByOldReg]
        Q -->|Input text with old pattern| R[Text]
        R -->|Regex replace| S[Text with new pattern]
    end

Summary

The utils.ts file offers essential helpers for:

• Validating the existence of conversation IDs.

• Extracting a unique list of document IDs referenced in conversations.

• Building or retrieving message reference objects aligned with assistant messages.

• Converting legacy text references to a current standardized format.

These utilities improve code maintainability, data integrity, and support backward compatibility within the chat system of the application.