Fanos 🏮

Fanos is a lightweight JavaScript promise-based library that simplifies sending asynchronous requests using the Beacon API. It ensures reliable, non-blocking transmission of data to a server, making it ideal for scenarios like analytics, logging, and tracking user interactions. However, it does but not guaranteed if the browser is closed suddenly.

To improve reliability, Fanos includes an optional fallback mechanism using Fetch and supports automatic retrying of failed requests. This ensures that your data is transmitted reliably, even in challenging network conditions.

Table of Contents

1. Features
2. Installation
   • Load From Path
   • CDN
   • ES Modules
3. Quickstart
   • Instance-Based Approach
   • Static Method (Global Configuration)
   • Flushing the Queue Manually
   • Destroying the Instance
4. Important Notes
5. Next Steps
6. Browser & Node.js Compatibility
7. Contributions
8. Changelog
9. License

Features

• ⏳ Asynchronous request sending: Uses the Beacon API for non-blocking requests.
• 🔄 Optional Fetch fallback: Enables Fetch as a backup if sendBeacon fails.
• 🔁 Automatic retry: Stores failed requests in localStorage and retries them.
• 🔄 Multiple payload formats: Supports JSON, FormData, URL-encoded data, and Blobs.
• 🧑‍💻 Custom headers: Allows adding headers for requests.
• 🐞 Debug mode: Logs internal operations for troubleshooting.

1. Installation

You can include Fanos in your project via a script tag or install it using npm:

npm install fanos

Load From Path

Include the library directly in your HTML:

<script src="path/to/fanos.umd.min.js"></script>

CDN

Use the library via a CDN:

<script src="https://cdn.jsdelivr.net/npm/fanos@latest/dist/fanos.umd.min.js"></script>

ES Modules

Import the library in your JavaScript project:

import Fanos from 'dist/fanos.esm'

2. Quickstart

Here’s how to get started with Fanos in just a few lines of code:

• Instance-Based Approach

const fanos = new Fanos({
   url: 'https://example.com/api/log',
});

const payload = {
   userId: 123,
   action: 'login',
   details: { browser: 'Chrome', os: 'Windows' },
};

fanos.send(payload)
   .then(() => console.log('Sent successfully'))
   .catch(err => console.error('Failed to send:', err));

• Static Method (Global Configuration)

Fanos.configure({
    url: 'https://example.com/api/log',
    debug: true,
});

Fanos.send(payload)
    .then(() => console.log('Sent successfully'))
    .catch(err => console.error('Failed to send:', err));

• Flushing the Queue Manually

The flush method sends all queued requests immediately.

fanos.flush()

• Destroying the Instance

The destroy method cleans up resources and stops retries:

fanos.destroy()

3. Important Notes

• Beacon API Dependency: Fanos relies on the Beacon API, to send data asynchronously to the server. Note that the Beacon API is specifically designed for sending data and does not support receiving responses from the server. For older browsers that do not support the Beacon API, you can enable the fallbackToFetch option to use Fetch as a fallback mechanism.
• Node.js Compatibility: Fanos is specifically designed for browser environments and is not compatible with Node.js. Ensure it is used in client-side applications only.
• Debugging: To assist with troubleshooting, you can enable the debug option. This will log internal operations and provide insights into the library's behavior during execution.

4. Next Steps

• Explore the full list of Configuration Options.
• Check out more examples for advanced usage.
• Refer to the detailed API documentation for all available methods and properties.

Browser & Node.js Compatibility

| Browser/Environment | Support | |---------------------|---------| | Chrome | Latest ✔ | | Firefox | Latest ✔ | | Safari | Latest ✔ | | Opera | Latest ✔ | | Edge | Latest ✔ | | Node.js | No ❌ |

Contributions

We welcome contributions! Please read the Contributions Guid to learn how to contribute.

Changelog

See Changelog for release details.

License

This package is open-source software licensed under the MIT license.