use-run-document.ts

Overview

The use-run-document.ts file defines a custom React hook named useHandleRunDocumentByIds which facilitates running or stopping the execution of a document by its ID. It leverages another custom hook, useRunDocument, to perform the actual document operation request.

This hook manages internal loading state specific to the given document ID, ensuring that concurrent operations on the same document are avoided. It provides an asynchronous function to trigger the run/stop process, optionally supporting deletion of the document during the operation.

Detailed Explanation

Hook: useHandleRunDocumentByIds

Purpose

useHandleRunDocumentByIds abstracts the logic for running or stopping a document workflow identified by a single document ID, with optional deletion. It encapsulates:

• Tracking the current active document ID being processed.

• Preventing duplicate simultaneous requests on the same document.

• Calling the underlying API/request hook useRunDocument with appropriate parameters.

• Providing a clean interface for React components to trigger run/stop actions and track loading status.

Signature

useHandleRunDocumentByIds(id: string): {
  handleRunDocumentByIds: (
    documentId: string,
    isRunning: boolean,
    shouldDelete?: boolean
  ) => Promise<void>;
  loading: boolean;
}

Parameters

• id: string
  The document ID for which the hook instance is scoped. This is used to determine if the current loading state corresponds to this specific document.

Returns

An object containing:

• handleRunDocumentByIds:
  An asynchronous function to trigger run/stop operations on a document.

• loading:
  A boolean indicating whether the operation is currently in progress for the provided id.

handleRunDocumentByIds function parameters:

• documentId: string
  The ID of the document to run or stop.

• isRunning: boolean
  If true, it triggers the "run" action (represented by run: 2), else the "stop" action (run: 1).

• shouldDelete?: boolean (optional, default: false)
  Indicates whether the document should be deleted after the operation.

Behavior and Implementation Details

• The hook internally uses the useRunDocument hook, which exposes:

  • runDocumentByIds: a function to send requests to run/stop documents by IDs.

  • loading: a global loading state indicating if any run request is in progress.

• The internal state currentId tracks the document ID currently being processed.

• The isLoading state is derived as loading && currentId === id && currentId !== '', ensuring that loading is only true when the current loading operation corresponds to this specific document ID.

• When handleRunDocumentByIds is called:

  • It first checks if the hook is already loading for this document to prevent duplicate requests.

  • Sets currentId to the document being processed.

  • Calls runDocumentByIds with parameters:

    • documentIds: array containing the single documentId.

    • run: numeric flag (2 to run, 1 to stop).

    • shouldDelete: passed through.

  • Upon success or failure, resets currentId to an empty string to clear the loading state.

Usage Example

import React from 'react';
import { useHandleRunDocumentByIds } from './use-run-document';

const DocumentRunner: React.FC<{ docId: string }> = ({ docId }) => {
  const { handleRunDocumentByIds, loading } = useHandleRunDocumentByIds(docId);

  const runDocument = () => {
    handleRunDocumentByIds(docId, true);
  };

  const stopDocument = () => {
    handleRunDocumentByIds(docId, false, true);
  };

  return (
    <div>
      <button onClick={runDocument} disabled={loading}>
        Run Document
      </button>
      <button onClick={stopDocument} disabled={loading}>
        Stop & Delete Document
      </button>
      {loading && <p>Processing document {docId}...</p>}
    </div>
  );
};

Interaction with Other Parts of the System

• useRunDocument Hook:
  This file depends on useRunDocument (imported from @/hooks/use-document-request), which is assumed to provide the core API interaction functionality for running and stopping documents. The runDocumentByIds function likely sends network requests to a backend service.

• React Components:
  This hook is designed to be consumed by React functional components that need to run or stop documents by ID, providing a simple interface to trigger these operations and track loading state.

• State Management:
  The internal usage of useState and the loading flag from useRunDocument enables coordinated UI state updates for document execution workflows.

Mermaid Diagram

classDiagram
    class useHandleRunDocumentByIds {
        -currentId: string
        -isLoading: boolean
        +handleRunDocumentByIds(documentId: string, isRunning: boolean, shouldDelete?: boolean): Promise<void>
        +loading: boolean
    }
    useHandleRunDocumentByIds ..> useRunDocument : uses
    class useRunDocument {
        +runDocumentByIds(params: { documentIds: string[]; run: number; shouldDelete: boolean }): Promise<void>
        +loading: boolean
    }

Summary

• Purpose: Provide a simple React hook to run or stop documents by ID with loading state management scoped per document.

• Core Functionality: Calls runDocumentByIds from useRunDocument with appropriate parameters, prevents concurrent operations on the same document, and exposes an async handler and loading flag.

• Usage: Suitable for React components managing document execution workflows.

• Interactions: Relies on useRunDocument for API calls; manages local state for UI responsiveness.

This file is a focused utility hook that encapsulates concerns related to running/stopping documents by IDs while handling concurrent request prevention and loading state management differentiated by document ID.