document-util.ts

Overview

The document-util.ts file provides a set of utility functions designed for handling document-related operations within the application. These utilities primarily focus on:

• Constructing highlight metadata for document chunks, useful for rendering annotations or highlights on documents.

• Determining file status and type for uploads and previews.

• Validating supported document types and image formats.

This utility module supports features related to document viewing, annotation, and file handling workflows, integrating with constants, interface definitions, and external libraries like antd and lodash.

Functions

1. buildChunkHighlights

buildChunkHighlights(
  selectedChunk: IChunk | IReferenceChunk,
  size: { width: number; height: number }
): Array<{
  id: string;
  comment: { text: string; emoji: string };
  content: { text: string };
  position: { boundingRect: object; rects: object[]; pageNumber: number };
}>

• Purpose: Generates an array of highlight objects for a given document chunk. Each highlight includes position information (bounding rectangles), unique ID, associated content, and an empty comment template.

• Parameters:

  • selectedChunk: An object implementing either IChunk or IReferenceChunk interface. It must contain a positions property, which is expected to be an array of arrays. Each inner array represents a highlight position on a page.

  • size: An object specifying the dimensions (width and height) of the container or document view area.

• Returns: An array of highlight objects, each with:

  • id: A unique UUID string.

  • comment: An object with empty text and emoji fields (placeholders for user annotations).

  • content: Contains the text content related to the chunk, preferring content_with_weight if available, otherwise content.

  • position: Contains bounding rectangle coordinates, an array of rectangles (for extensibility), and the page number.

• Usage Example:

  const chunk: IChunk = {
    positions: [
      [0, 10, 50, 20, 40],  // page 0, x1=10, x2=50, y1=20, y2=40
      [1, 15, 60, 25, 45],  // page 1, ...
    ],
    content: "Example content",
  };
  const size = { width: 100, height: 200 };
  const highlights = buildChunkHighlights(chunk, size);
  

• Implementation Details:

  • Validates that positions is an array of arrays.

  • Each position array is expected to have 5 elements: [pageNumber, x1, x2, y1, y2].

  • Uses uuid to generate unique IDs for each highlight.

  • Uses lodash.get to safely retrieve content fields.

2. isFileUploadDone

isFileUploadDone(file: UploadFile): boolean

• Purpose: Checks if a file upload has completed successfully.

• Parameters:

  • file: An UploadFile object from the antd library, representing a file in the upload process.

• Returns: true if the file's status is 'done', otherwise false.

• Usage Example:

  const file: UploadFile = { status: 'done', name: 'example.pdf' };
  if (isFileUploadDone(file)) {
    console.log('Upload finished');
  }
  

3. getExtension

getExtension(name: string): string

• Purpose: Extracts the file extension from a filename.

• Parameters:

  • name: The full filename string.

• Returns: The file extension in lowercase, or empty string if none found.

• Usage Example:

  getExtension('document.PDF'); // Returns 'pdf'
  getExtension('archive');      // Returns ''
  

4. isPdf

isPdf(name: string): boolean

• Purpose: Checks if a given filename corresponds to a PDF file.

• Parameters:

  • name: The filename string.

• Returns: true if the file extension is 'pdf', otherwise false.

• Usage Example:

  isPdf('report.pdf');  // true
  isPdf('image.png');   // false
  

5. getUnSupportedFilesCount

getUnSupportedFilesCount(message: string): number

• Purpose: Calculates the number of unsupported files based on an input message string.

• Parameters:

  • message: A string containing filenames or error messages separated by newline characters (\n).

• Returns: The count of unsupported files, determined by the number of lines in the message.

• Usage Example:

  const message = 'file1.exe\nfile2.bat\nfile3.scr';
  const count = getUnSupportedFilesCount(message);  // Returns 3
  

6. isSupportedPreviewDocumentType

isSupportedPreviewDocumentType(fileExtension: string): boolean

• Purpose: Determines if a file extension is among the supported document types for preview.

• Parameters:

  • fileExtension: The file extension string (expected in lowercase).

• Returns: true if the extension is supported, otherwise false.

• Usage Example:

  isSupportedPreviewDocumentType('pdf');  // true if included in SupportedPreviewDocumentTypes
  isSupportedPreviewDocumentType('exe');  // false
  

7. isImage

isImage(image: string): boolean

• Purpose: Checks if a given file extension or type string corresponds to a recognized image format.

• Parameters:

  • image: The image file type or extension string.

• Returns: true if the image type is in the predefined list Images or is 'svg'.

• Usage Example:

  isImage('png');  // true if 'png' in Images
  isImage('svg');  // true
  isImage('pdf');  // false
  

Important Implementation Details

• UUID Generation: The buildChunkHighlights function uses the uuid library to assign unique IDs to each highlight, ensuring uniqueness across the application.

• Safe Property Access: The use of lodash.get prevents runtime errors when accessing nested or optional properties (content_with_weight and content).

• Position Format: The positions array for chunks follows a specific format where each element is an array describing [pageNumber, x1, x2, y1, y2], which allows flexible multi-rectangle highlights across pages.

• Constants Dependency: This file relies on constants such as Images and SupportedPreviewDocumentTypes imported from a common constants module, centralizing the management of supported types.

• File Status: The file upload checking integrates smoothly with Ant Design's upload component by using its UploadFile type and status conventions.

Interaction with Other Parts of the System

• Constants: Imports Images and SupportedPreviewDocumentTypes from the common constants, ensuring consistent definition of supported file types and image formats across the app.

• Interfaces: Uses IChunk and IReferenceChunk interfaces from the database-related modules to type-check chunk objects, indicating tight coupling with the database knowledge and chat subsystems.

• UI Components: Utilizes UploadFile type from antd upload components, showing this module supports file upload handling in the UI.

• Utility Libraries: Depends on lodash.get for safe deep access and uuid for ID generation.

This file is a utility layer enabling document preview, annotation, and upload workflows, likely invoked by document viewer components, file upload handlers, and annotation managers.

Diagram: Function Flowchart

flowchart TD
    A[buildChunkHighlights] -->|uses| B[lodash.get]
    A -->|generates| C[UUID for id]
    D[isFileUploadDone] --> E[Checks file.status === 'done']
    F[getExtension] --> G[Extracts extension from filename]
    H[isPdf] --> F
    I[getUnSupportedFilesCount] --> J[Counts lines in message]
    K[isSupportedPreviewDocumentType] --> L[Checks SupportedPreviewDocumentTypes]
    M[isImage] --> N[Checks Images + 'svg']

• The flowchart shows the main functions in the file and their dependencies or operations.

• buildChunkHighlights is the most complex function, relying on lodash and uuid.

• Other functions mainly perform simple checks or string operations related to file type and status.

Summary

The document-util.ts file encapsulates essential helper functions for document chunk highlighting, file type validation, and upload status checking. It integrates with key interface definitions and constants, supporting document preview and annotation features in the application. The utilities are designed for robustness, extensibility, and easy integration with UI components and backend data structures.