Skip to content

Commit 5d5c53a

Browse files
nassirynassiry
committed
Initial commit
0 parents  commit 5d5c53a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+10426
-0
lines changed

‎.github/workflows/release.yml

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
branches:
6+
- main # Runs only when code is pushed to main
7+
8+
jobs:
9+
release:
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- name: Checkout repository
14+
uses: actions/checkout@v3
15+
with:
16+
fetch-depth: 0 # Required for versioning
17+
18+
- name: Cache node_modules
19+
uses: actions/cache@v3
20+
with:
21+
path: node_modules
22+
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
23+
restore-keys: |
24+
${{ runner.os }}-node-
25+
26+
- name: Install dependencies
27+
run: npm install
28+
29+
- name: Build the package
30+
run: npm run build
31+
32+
- name: Run Semantic Release
33+
env:
34+
GITHUB_TOKEN: ${{ secrets.GH_PAT }}
35+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
36+
run: npx semantic-release

‎.gitignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.idea
2+
.vscode
3+
.DS_Store
4+
Thumbs.db
5+
*.log
6+
node_modules/

‎.prettierignore

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Ignore artifacts:
2+
node_modules/
3+
CHANGELOG.md
4+
docs/
5+
examples/
6+
dist/
7+
eslint.config.mjs
8+
rollup.config.js
9+
package.json
10+
README.md

‎.prettierrc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"semi": false,
3+
"singleQuote": true,
4+
"tabWidth": 2,
5+
"trailingComma": "all"
6+
}

‎.releaserc.json

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"branches": ["main"],
3+
"plugins": [
4+
"@semantic-release/commit-analyzer",
5+
"@semantic-release/release-notes-generator",
6+
"@semantic-release/changelog",
7+
["@semantic-release/npm", {
8+
"npmPublish": true
9+
}],
10+
["@semantic-release/git", {
11+
"assets": ["package.json", "package-lock.json", "CHANGELOG.md", "dist/**/*"],
12+
"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
13+
}],
14+
"@semantic-release/github"
15+
]
16+
}

‎CHANGELOG.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
6+
7+
## [1.0.0] - 2025-02-09
8+
9+
### Added
10+
11+
- Initial release

‎CONTRIBUTIONS.md

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Contributions
2+
3+
Contributions are welcome and greatly appreciated! Whether you're fixing a bug, adding a feature, or improving documentation, your efforts help make **Fanos** better for everyone. Please follow these guidelines to ensure consistency and quality across the project.
4+
5+
## Table of contents
6+
1. [Install Development Dependencies](#1-install-development-dependencies)
7+
2. [Submit Issues or Feature Requests](#2-submit-issues-or-feature-requests)
8+
3. [Fork and Create a Pull Request](#3-fork-and-create-a-pull-request)
9+
4. [Coding Standards](#4-coding-standards)
10+
5. [Linting](#5-linting)
11+
6. [Formatting](#6-formatting)
12+
7. [Example for New Features or Bug Fixes](#7-example-for-new-features-or-bug-fixes)
13+
8. [Build](#8-build)
14+
9. [Submit Pull Request](#9-submit-pull-request)
15+
10. [Commit Messages](#10-commit-messages)
16+
11. [Documentation](#11-documentation)
17+
18+
## 1. Install Development Dependencies
19+
Before starting, make sure to install the necessary development dependencies:
20+
21+
```bash
22+
npm install
23+
```
24+
This will install all the required dependencies listed in the `package.json`, including ESLint, Prettier, and Rollup.
25+
26+
## 2. Submit Issues or Feature Requests
27+
- For **bug reports** or **feature requests**, please create an issue on the repository.
28+
- Provide as much detail as possible to help us understand the issue or feature request.
29+
30+
## 3. Fork and Create a Pull Request
31+
- **Fork** the repository and create a **pull request (PR)** with your changes.
32+
- Ensure that your PR is **up-to-date** with the latest version of the `main` branch to avoid conflicts.
33+
- For a step-by-step guide on creating PRs, refer to [GitHub's documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
34+
35+
## 4. Coding Standards
36+
- Your code should adhere to the project's coding standards.
37+
- Run **linting** and **formatting** checks to ensure your code is clean and consistent.
38+
39+
## 5. Linting
40+
- The project uses **ESLint** to enforce code quality and consistency. Before submitting your PR, ensure that:
41+
- **Run ESLint**: Lint your code with `eslint src`
42+
```bash
43+
npm run lint
44+
```
45+
- **Fix Issues**: You can automatically fix most linting issues using the `--fix` flag.
46+
```bash
47+
npm run lint:fix
48+
```
49+
50+
## 6. Formatting
51+
52+
The project uses **Prettier** to maintain consistent code formatting. To format your code before submitting a PR:
53+
- **Format your code** with Prettier:
54+
```bash
55+
npm run format
56+
```
57+
58+
## 7. Example for New Features or Bug Fixes
59+
- If you're adding a new feature or fixing a bug, please include relevant examples or tests (if applicable) that demonstrate the fix or feature in action.
60+
- Ensure that your changes are covered by unit tests or integration tests.
61+
- If you're unsure how to write tests, feel free to ask for help in your PR!
62+
63+
## 8. Build
64+
- If your changes include updates to the build process, ensure that you test it using **Rollup**:
65+
```bash
66+
npm run build
67+
```
68+
69+
## 9. Submit Pull Request
70+
71+
Once your changes are complete, **submit your pull request**. Be sure to provide a clear description of what your changes do and any additional context.
72+
73+
74+
## 10. Commit Messages
75+
- Follow the [Conventional Commits](https://www.conventionalcommits.org/) format:
76+
77+
### Example
78+
79+
- `feat(core)`: add support for JSON payload type
80+
- `fix(api)`: resolve issue with failed request retries
81+
- `docs(readme)`: update installation instructions
82+
83+
### Types:
84+
- `feat`: A new feature.
85+
- `fix`: A bug fix.
86+
- `docs`: Documentation changes.
87+
- `style`: Code style changes.
88+
- `refactor`: Code refactoring (no functional changes).
89+
- `test`: Adding or updating tests.
90+
- `chore`: Maintenance tasks (dependency updates).
91+
92+
## 11. Documentation
93+
- Update the relevant documentation when adding new features or making changes.
94+
- Use clear and concise language.
95+
- Include examples where applicable.
96+
- Follow the Markdown formatting guidelines.
97+
98+
By following these steps, you can ensure that your contributions are aligned with the project's standards and easy to integrate. Feel free to submit any issues or pull requests to improve the project!
99+

‎LICENSE

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2025 A.S Nasseri
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6+
7+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8+
9+
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Fanos 🏮
2+
3+
**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**.
4+
5+
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.
6+
7+
8+
## Table of Contents
9+
10+
1. [Features](#features)
11+
2. [Installation](#1-installation)
12+
- [Load From Path](#browser)
13+
- [CDN](#cdn)
14+
- [ES Modules](#es-modules)
15+
3. [Quickstart](#2-quickstart)
16+
- [Instance-Based Approach](#instance-based-approach)
17+
- [Static Method (Global Configuration)](#static-method-global-configuration)
18+
- [Flushing the Queue Manually](#flushing-the-queue-manually)
19+
- [Destroying the Instance](#destroying-the-instance)
20+
4. [Important Notes](#3-important-notes)
21+
5. [Next Steps](#4-next-steps)
22+
6. [Browser & Node.js Compatibility](#browser--nodejs-compatibility)
23+
7. [Contributions](#contributions)
24+
8. [Changelog](#changelog)
25+
9. [License](#license)
26+
27+
## Features
28+
29+
- ⏳ **Asynchronous request sending**: Uses the `Beacon API` for non-blocking requests.
30+
- 🔄 **Optional Fetch fallback**: Enables `Fetch` as a backup if `sendBeacon` fails.
31+
- 🔁 **Automatic retry**: Stores failed requests in `localStorage` and retries them.
32+
- 🔄 **Multiple payload formats**: Supports `JSON`, `FormData`, `URL-encoded data`, and `Blobs`.
33+
- 🧑‍💻 **Custom headers**: Allows adding `headers` for requests.
34+
- 🐞 **Debug mode**: Logs internal operations for troubleshooting.
35+
36+
## 1. Installation
37+
38+
You can include **Fanos** in your project via a script tag or install it using `npm`:
39+
40+
```bash
41+
npm install fanos
42+
```
43+
44+
#### Load From Path
45+
46+
Include the library directly in your HTML:
47+
48+
```html
49+
<script src="path/to/fanos.js"></script>
50+
```
51+
#### CDN
52+
53+
Use the library via a CDN:
54+
55+
```html
56+
<script src="https://cdn.jsdelivr.net/npm/fanos@latest/dist/fanos.umd.min.js"></script>
57+
```
58+
59+
#### ES Modules
60+
61+
Import the library in your JavaScript project:
62+
63+
```javascript
64+
import Fanos from 'dist/fanos.esm'
65+
```
66+
67+
## 2. Quickstart
68+
69+
Here’s how to get started with **Fanos** in just a few lines of code:
70+
71+
- ### Instance-Based Approach
72+
73+
```javascript
74+
const fanos = new Fanos({
75+
url: 'https://example.com/api/log',
76+
});
77+
78+
const payload = {
79+
userId: 123,
80+
action: 'login',
81+
details: { browser: 'Chrome', os: 'Windows' },
82+
};
83+
84+
fanos.send(payload)
85+
.then(() => console.log('Sent successfully'))
86+
.catch(err => console.error('Failed to send:', err));
87+
```
88+
89+
- ### Static Method (Global Configuration)
90+
91+
```javascript
92+
Fanos.configure({
93+
url: 'https://example.com/api/log',
94+
debug: true,
95+
});
96+
97+
Fanos.send(payload)
98+
.then(() => console.log('Sent successfully'))
99+
.catch(err => console.error('Failed to send:', err));
100+
```
101+
- ### Flushing the Queue Manually
102+
103+
The `flush` method sends all queued requests immediately.
104+
105+
```javascript
106+
fanos.flush()
107+
```
108+
109+
- ### Destroying the Instance
110+
111+
The `destroy` method cleans up resources and stops retries:
112+
113+
```javascript
114+
fanos.destroy()
115+
```
116+
117+
## 3. Important Notes
118+
119+
- **Beacon API Dependency**: Fanos relies on the [Beacon API](https://w3c.github.io/beacon/), which is supported in modern browsers. For older browsers, enable the `fallbackToFetch` option to use `Fetch` as a fallback.
120+
121+
- **Node.js Compatibility**: Fanos is designed for browser environments and is **not compatible with Node.js**.
122+
123+
- **Debugging**: Enable the `debug` option to log internal operations for troubleshooting.
124+
125+
## 4. Next Steps
126+
127+
- Explore the full list of [Configuration Options](/docs/configuration.md).
128+
- Check out more [examples](/examples/index.md) for advanced usage.
129+
- Refer to the detailed [API documentation](/docs/api.md) for all available methods and properties.
130+
131+
## Browser & Node.js Compatibility
132+
133+
| Browser/Environment | Support |
134+
|---------------------|---------|
135+
| Chrome | Latest ✔ |
136+
| Firefox | Latest ✔ |
137+
| Safari | Latest ✔ |
138+
| Opera | Latest ✔ |
139+
| Edge | Latest ✔ |
140+
| Node.js | No ❌ |
141+
142+
143+
## Contributions
144+
145+
We welcome contributions! Please read the [Contributions Guid](CONTRIBUTIONS.md) to learn how to contribute.
146+
147+
## Changelog
148+
149+
See [Changelog](CHANGELOG.md) for release details.
150+
151+
## License
152+
153+
This package is open-source software licensed under the [MIT license](LICENSE).

0 commit comments

Comments
 (0)