https://github.com/nassiry/fanosjs
Fanos is a lightweight JavaScript promise-based library that simplifies sending asynchronous requests using the Beacon API.
https://github.com/nassiry/fanosjs
asynchronous asynchronous-requests beacon non-blocking requests
Last synced: about 1 month ago
JSON representation
Fanos is a lightweight JavaScript promise-based library that simplifies sending asynchronous requests using the Beacon API.
- Host: GitHub
- URL: https://github.com/nassiry/fanosjs
- Owner: nassiry
- License: mit
- Created: 2025-02-18T07:05:26.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-02-23T04:24:24.000Z (3 months ago)
- Last Synced: 2025-03-29T01:22:35.495Z (about 2 months ago)
- Topics: asynchronous, asynchronous-requests, beacon, non-blocking, requests
- Language: JavaScript
- Homepage: https://github.com/nassiry/fanosjs
- Size: 116 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Fanos 🏮
**Fanos** is a lightweight JavaScript `promise-based` library that simplifies sending asynchronous requests using the [Beacon API](https://w3c.github.io/beacon/). 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](#features)
2. [Installation](#1-installation)
- [Load From Path](#browser)
- [CDN](#cdn)
- [ES Modules](#es-modules)
3. [Quickstart](#2-quickstart)
- [Instance-Based Approach](#instance-based-approach)
- [Static Method (Global Configuration)](#static-method-global-configuration)
- [Flushing the Queue Manually](#flushing-the-queue-manually)
- [Destroying the Instance](#destroying-the-instance)
4. [Important Notes](#3-important-notes)
5. [Next Steps](#4-next-steps)
6. [Browser & Node.js Compatibility](#browser--nodejs-compatibility)
7. [Contributions](#contributions)
8. [Changelog](#changelog)
9. [License](#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`:
```bash
npm install fanos
```
#### Load From Path
Include the library directly in your HTML:
```html
```
#### CDN
Use the library via a CDN:
```html
```
#### ES Modules
Import the library in your JavaScript project:
```javascript
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
```javascript
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)
```javascript
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.
```javascript
fanos.flush()
```
- ### Destroying the Instance
The `destroy` method cleans up resources and stops retries:
```javascript
fanos.destroy()
```
## 3. Important Notes
- **Beacon API Dependency**: Fanos relies on the [Beacon API](https://w3c.github.io/beacon/), 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](/docs/configuration.md).
- Check out more [examples](/examples/index.md) for advanced usage.
- Refer to the detailed [API documentation](/docs/api.md) 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](CONTRIBUTIONS.md) to learn how to contribute.
## Changelog
See [Changelog](CHANGELOG.md) for release details.
## License
This package is open-source software licensed under the [MIT license](LICENSE).