🚀 Nexli (API Request Manager)

Nexli is a powerful, lightweight, and framework-agnostic API client wrapper for JavaScript and TypeScript. It abstracts complex network concerns like retries, rate limiting, request queuing, and offline synchronization so you can focus on your application logic.

✨ Features

• 🛡️ Smart Retries: Automatic retries on transient server errors (5xx) and timeouts, with configurable backoff.
• 🚦 Rate Limiting: Controls the request velocity to prevent overwhelming the backend API.
• 📦 Request Queue: Manages request execution based on concurrency limits and priority.
• 🔌 Offline Mode: Automatically persists requests to Local Storage when the network is unavailable and syncs them upon reconnection.
• 🌐 Adapter Support: Compatible with both Fetch (default) and Axios.
• ✅ Type-Safe: Fully written in TypeScript for robust integration.

📦 Installation

Install Nexli into your project using npm or yarn:

npm install nexli
# or
yarn add nexli

🎮 Interactive Demo & Documentation

Don't just take our word for it see Nexli in action.

We have built a dedicated Playground where you can simulate real-world network chaos. Toggle Offline Mode, trigger 500 Server Errors, and watch how Nexli's Priority Queue and Auto-Retry System handle the traffic gracefully.

⚡ Try it out: Experience the "Chaos Mode" and visualize the Request Queue in real-time.

Explore Full Documentation →

🚀 Where Should You Use Nexli? (Backend vs. Frontend)

Nexli is generally more suitable for Frontend (React/JSX) applications, but it can also be used in the Backend (Node.js) depending on your needs.

Here is a breakdown of where Nexli is most effective and why:

1. ⚛️ Frontend (React, Vue, etc.) - Most Perfect Fit

The core features that make Nexli unique are primarily designed for the browser environment: | Feature | Reason | | :--- | :--- | | 🔌 Offline Mode / Synchronization | This feature relies on Local Storage (available only in the browser). It automatically saves requests when the user is offline and syncs them upon reconnection. This is a key feature that makes Nexli ideal for the frontend. | | 🚦 Rate Limiting | It helps ensure the client (browser) does not overwhelm the backend API by controlling the request velocity.| | 📦 Request Queueing | Managing and prioritizing requests when a user performs many quick actions is a common frontend concern. | | 🌐 Adapter Support | The default adapter is the native Fetch API, which is a browser standard. |

Conclusion: If your priority is Offline Synchronization, managing network stability for users, and controlling front-end request queues, Nexli should be used in your React/Frontend code.

2. 🟢 Backend (Node.js) - Viable (But Less Necessary)

You can certainly use Nexli in a Node.js environment, especially when configured with the Axios adapter.

| Feature | Reason | | :--- | :--- | | 🛡️ Smart Retries | When your Node.js server calls a Third-Party API (like a payment service or data feed), automatic retries on transient server errors (5xx) are highly beneficial for reliability. | | 📦 Request Queueing | If your server needs to send a large volume of requests to a single external service, queueing and concurrency limits can prevent overloading that external API.| | 🔌 Offline Sync | This feature will not work out-of-the-box in Node.js, as it relies on the browser's Local Storage. |

Conclusion: In the backend, you often have other robust ways to handle retries (e.g., built-in features of libraries like Axios or specific SDKs like the OpenAI one you are using). If you specifically need a unified solution for queueing and advanced retries when talking to other REST APIs, you can use it. However, its biggest advantage (Offline Sync) is lost here.

🛠️ Usage Guide

Step 1: Initialize the Client

Instantiate ApiClient with your required configuration.

TypeScript

import { ApiClient } from 'nexli';

const api = new ApiClient({
    // Set the base URL for all requests
    baseUrl: '[https://jsonplaceholder.typicode.com](https://jsonplaceholder.typicode.com)', 
    
    // Configure Queue concurrency
    queue: {
        concurrency: 5, // Process up to 5 requests concurrently
    },
    
    // Configure Rate Limiting (e.g., 5 requests per 2000ms)
    rateLimit: {
        maxRequests: 5,
        perMilliseconds: 2000, 
    },
});

Step 2: Making Requests

Nexli supports all standard HTTP methods (get, post, put, delete).

A. Basic GET Request

TypeScript

async function fetchPost() {
    try {
        const response = await api.get('/posts/1');
        console.log("Post Title:", response.data.title);
    } catch (error) {
        console.error("API Error:", error);
    }
}
fetchPost();

B. POST Request with Priority

You can assign priority to ensure critical requests are processed first in the queue (1 is lowest, 10 is highest).

TypeScript

async function sendHighPriorityLog() {
    const logData = {
        message: 'Critical event occurred!',
        timestamp: Date.now()
    };
    
    // Options are passed as the third argument
    const response = await api.post('/logs', logData, {
        priority: 10 // Highest priority
    });
    
    console.log("Log sent, Status:", response.status);
}

Step 3: Advance Features Setup

A. Configuring Retry Strategy

Set the maximum attempts and the HTTP status codes that should trigger a retry.

TypeScript

const retryClient = new ApiClient({
    baseUrl: '[https://api.example.com](https://api.example.com)',
    retry: {
        maxAttempts: 4, 
        delayMs: 1000,
        // Only retry on common server/timeout errors
        statusCodes: [500, 503, 408, 429], 
    },
});

B. Offline Synchronization

Enable offline mode to automatically save failed network requests for later synchronization.

TypeScript

const offlineClient = new ApiClient({
    baseUrl: '[https://api.analytics.com](https://api.analytics.com)',
    offline: {
        enabled: true, // Turns on offline storage
        storageKey: 'my_app_pending_requests',
        limit: 50, // Maximum number of requests to store
    },
});

// If the device is offline, this request will be stored and sent later.
offlineClient.post('/analytics', { event: 'checkout_fail' });

Note: The synchronization process is triggered automatically upon client initialization. You can manually trigger it using await client.syncOfflineRequests();.

⚙️ Configuration Options

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | baseUrl | string | "" | The root URL for all API requests. | | debug | boolean | false | Enables detailed logs in the console for debugging. | | adapter | 'fetch'/'axios' | 'fetch' | Network execution engine. | | retry.maxAttempts | number | 3 | Max number of times to retry on failure. | | queue.concurrency | number | 5 | Maximum requests processed simultaneously. | | rateLimit.maxRequests | number | 10 | Max requests allowed in the time window defined by perMilliseconds. | | offline.enabled | boolean | false | Enables offline storage and auto-sync using Local Storage. |

🤝 Contributing

Contributions are welcome! Please ensure all tests pass before submitting a Pull Request.

• Fork the repository.
• Run the build and tests: npm run build && npm test.
• Submit your Pull Request

👤 Author & Contributor

This package is maintained and developed by Hamza Tayyab. I am passionate about creating clean, efficient, and secure frontend tools. Feel free to connect or check out my other projects!

| Platform | Link | | :--- | :--- | | 🌐 Portfolio | https://linktr.ee/hm.za | | 📧 Email | [email protected] | | 💻 GitHub | Follow me on GitHub https://github.com/hmzatayab | | 🎁 Other Packages | Check out my other open-source projects https://www.npmjs.com/~hamzatayab |

📄 License

Nexli is released under the MIT License.