Configuration Options

A comprehensive overview of all available configuration options in v2.0.0.

Here's a breakdown of the configuration options available in hmm-api v2.0.0:

1. baseUrl

  • Default: None
  • Purpose: Sets a common base URL for all API requests.
  • Example: 
    const apiClient = new ApiClient({ baseUrl: "https://api.example.com" });

2. returnParsedError

  • Default: false
  • Purpose: Returns clean, parsed error messages instead of raw error objects.
  • Example: 
    const apiClient = new ApiClient({ returnParsedError: true });
// Now response.error will be a clean string message

3. globalHeaders

  • Default: None
  • Purpose: Sets headers included in all requests.
  • Example: 
    const apiClient = new ApiClient({
  globalHeaders: {
    Authorization: "Bearer your_token",
    "Content-Type": "application/json",
  },
});

4. showGlobalError

  • Default: true (in browser), false (in Node.js)
  • Purpose: Controls whether global error callbacks are triggered.
  • Example: 
    const apiClient = new ApiClient({ showGlobalError: true });

5. showGlobalSuccess

  • Default: false
  • Purpose: Controls whether global success callbacks are triggered.
  • Example: 
    const apiClient = new ApiClient({ showGlobalSuccess: true });

6. onSuccess

  • Default: Console log function
  • Purpose: Global callback function executed on successful requests.
  • Example: 
    const apiClient = new ApiClient({
  onSuccess: (response) => {
    console.log("✅ Success:", response.data);
    // Show success notification, update UI, etc.
  },
});

7. onError

  • Default: Console error function
  • Purpose: Global callback function executed on failed requests.
  • Example: 
    const apiClient = new ApiClient({
  onError: (response) => {
    console.error("❌ Error:", response.error);
    // Show error notification, log to service, etc.
  },
});

8. credentials

  • Default: same-origin
  • Purpose: Controls credential handling.
  • Example: 
    const apiClient = new ApiClient({ credentials: "include" });

9. timeout

  • Default: 30000 (30 seconds)
  • Purpose: Global timeout for all requests in milliseconds.
  • Example: 
    const apiClient = new ApiClient({
  timeout: 15000, // 15 seconds
});

Per-Request Options (New in v2.0.0)

All HTTP methods now support these additional per-request options:

finally

  • Purpose: Cleanup function that runs after request completion (success or failure).
  • Example: 
    const response = await api.get("/users", {
  finally: () => {
    hideLoadingSpinner();
    enableButton();
  },
});

onSuccess (per-request)

  • Purpose: Override global success callback for this specific request.
  • Example: 
    const response = await api.post("/users", userData, {
  onSuccess: (response) => {
    showSuccessMessage("User created successfully!");
  },
});

onError (per-request)

  • Purpose: Override global error callback for this specific request.
  • Example: 
    const response = await api.get("/users", {
  onError: (response) => {
    showCustomErrorDialog(response.error);
  },
});

New Advanced Options (v2.0.0)

onUploadProgress

  • Purpose: Track file upload progress.
  • Example: 
    const response = await api.post("/upload", formData, {
  onUploadProgress: (progress) => {
    console.log(`Upload: ${progress.percentage}%`);
    updateProgressBar(progress.percentage);
  },
});

onDownloadProgress

  • Purpose: Track file download progress.
  • Example: 
    const response = await api.get("/download/file.zip", {
  onDownloadProgress: (progress) => {
    console.log(`Download: ${progress.percentage}%`);
    updateProgressBar(progress.percentage);
  },
});

timeout (per-request)

  • Purpose: Override global timeout for specific requests.

  • Example:

    // Quick health check
const health = await api.get("/health", { timeout: 3000 });

// Long file upload
const upload = await api.post("/upload", data, { timeout: 60000 });

poll (per-request)

  • Purpose: Automatically poll an endpoint until a condition is met.

  • Example:

    const result = await api.get("/job/status", {
  poll: {
    interval: 2000, // Poll every 2 seconds
    maxAttempts: 10,
    pollId: "job-status-check", // Optional custom poll ID
    stopCondition: (response) => response.data.status === "completed",
    onPollSuccess: (response, attempt) => {
      console.log(`Attempt ${attempt}: ${response.data.progress}%`);
    },
  },
});

// Check if it's a polling result
if ("finalResponse" in result) {
  console.log("Polling completed:", result.finalResponse.data);
  console.log("Poll ID:", result.pollId); // "job-status-check"
}

// Stop specific polling operation
api.stopPolling("job-status-check");

Instance Methods (New in v2.0.0)

destroy()

  • Purpose: Cleanup method to prevent memory leaks and stop all active operations.

  • Example:

    const api = new ApiClient({ baseUrl: "/api" });

// Later, when component unmounts or app closes
api.destroy();

// Any further API calls will throw an error

stopAllPolling()

  • Purpose: Stop all active polling operations at once.

  • Example:

    const api = new ApiClient({ baseUrl: "/api" });

// Start multiple polling operations
api.get("/status1", { poll: { interval: 1000 } });
api.get("/status2", { poll: { interval: 2000 } });

// Stop all polling
api.stopAllPolling();

getActivePollingCount()

  • Purpose: Get the number of currently active polling operations.

  • Example:

    const api = new ApiClient({ baseUrl: "/api" });

console.log(`Active polls: ${api.getActivePollingCount()}`); // 0

api.get("/status", { poll: { interval: 1000 } });
console.log(`Active polls: ${api.getActivePollingCount()}`); // 1

getActivePollingIds()

  • Purpose: Get an array of all currently active polling operation IDs.

  • Example:

    const api = new ApiClient({ baseUrl: "/api" });

// Start multiple polling operations
api.get("/status", { poll: { interval: 1000, pollId: "status-check" } });
api.get("/health", { poll: { interval: 2000, pollId: "health-check" } });

const activeIds = api.getActivePollingIds();
console.log(activeIds); // ["status-check", "health-check"]

stopPolling(pollId)

  • Purpose: Stop a specific polling operation by its ID.

  • Example:

    const api = new ApiClient({ baseUrl: "/api" });

// Start polling with custom ID
const result = await api.get("/status", {
  poll: {
    interval: 1000,
    pollId: "status-check",
  },
});

// Stop specific polling operation
const stopped = api.stopPolling("status-check");
console.log(`Polling stopped: ${stopped}`); // true if successful

setAuthToken(token)

  • Purpose: Set or update the authorization token.

  • Example:

    const api = new ApiClient();

api.setAuthToken("Bearer your-token");
// All subsequent requests will include this token

setGlobalHeaders(headers)

  • Purpose: Add or update global headers.

  • Example:

    const api = new ApiClient();

api.setGlobalHeaders({
  "X-API-Version": "v2",
  "X-Client-ID": "web-app",
});

setShowGlobalError(show)

  • Purpose: Enable or disable global error callback execution.

  • Example:

    const api = new ApiClient();

api.setShowGlobalError(false); // Disable global error callbacks

setShowGlobalSuccess(show)

  • Purpose: Enable or disable global success callback execution.

  • Example:

    const api = new ApiClient();

api.setShowGlobalSuccess(true); // Enable global success callbacks

setOnSuccess(callback)

  • Purpose: Update the global success callback.

  • Example:

    const api = new ApiClient();

api.setOnSuccess((response) => {
  console.log("New success handler:", response.data);
});

setOnError(callback)

  • Purpose: Update the global error callback.

  • Example:

    const api = new ApiClient();

api.setOnError((response) => {
  console.error("New error handler:", response.error);
});

Memory Management Best Practices

React Component Example

import { useEffect, useRef } from "react";
import ApiClient from "hmm-api";

const Dashboard = () => {
  const apiRef = useRef(null);

  useEffect(() => {
    // Create API client
    apiRef.current = new ApiClient({
      baseUrl: "/api",
      onSuccess: (response) => {
        console.log("Request succeeded");
      },
    });

    // Cleanup on unmount
    return () => {
      if (apiRef.current) {
        apiRef.current.destroy();
      }
    };
  }, []);

  const handleStartPolling = async () => {
    if (apiRef.current) {
      const result = await apiRef.current.get("/status", {
        poll: {
          interval: 2000,
          onPollSuccess: (response) => {
            console.log("Status updated:", response.data);
          },
        },
      });
    }
  };

  const handleStopPolling = () => {
    if (apiRef.current) {
      apiRef.current.stopAllPolling();
    }
  };

  return (
    <div>
      <button onClick={handleStartPolling}>Start Polling</button>
      <button onClick={handleStopPolling}>Stop All Polling</button>
      <p>Active polls: {apiRef.current?.getActivePollingCount() || 0}</p>
    </div>
  );
};

By customizing these options and using the new instance methods, you can tailor hmm-api v2.0.0 to your specific project needs, ensuring a robust and flexible HTTP client solution with enhanced callback control, progress tracking, timeout management, automatic polling capabilities, and proper memory management.