accessio 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 **salvatorecorvaglia** (https://github.com/salvatorecorvaglia)
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/README.md

@@ -0,0 +1,487 @@
+# accessio 🎯
+
+**Fast, flexible HTTP client for Node.js and browsers — simple, modular, and dependency-free** — lightweight, modern, zero dependencies.
+
+---
+
+## ✨ Features
+
+- 🚀 **Promise-based** — works seamlessly with `async`/`await`
+- 🌐 **Isomorphic** — runs in both browser and Node.js (≥ 18)
+- 🪶 **Zero dependencies** — lightweight, built on native `fetch`
+- 🔄 **Interceptors** — transform requests and responses globally
+- ⚙️ **Configurable instances** — create multiple API clients with custom defaults
+- 🛡️ **Error handling** — structured `AccessioError` with status, config, and response
+- 📦 **Dual format** — supports both ESM and CommonJS
+- 📐 **TypeScript support** — full type definitions included
+- ⏱️ **Timeout support** — built-in request timeout via `AbortController`
+- 🔧 **Transform pipelines** — customize request/response data transformation
+- ♻️ **Automatic Retries** — built-in retry logic with exponential backoff and jitter
+- ⏱️ **Duration tracking** — every response includes a `duration` field in milliseconds
+- 🚥 **Rate Limiter** — limit concurrent requests with acquire/release/destroy lifecycle
+- 🐞 **Debug Mode** — structured console logging for outgoing requests and responses
+- 🎯 **Familiar API** — intuitive, developer-friendly interface
+
+---
+
+## 📦 Installation
+
+accessio is available on both the official npm registry (unscoped) and GitHub Packages (scoped).
+
+```bash
+# Recommended: Standard npm registry
+npm install accessio
+
+# Alternative: GitHub Packages
+npm install @salvatorecorvaglia/accessio
+```
+
+---
+
+## 🚀 Quick Start
+
+```typescript
+import accessio from "accessio";
+
+// GET request
+const response = await accessio.get("https://api.example.com/users");
+console.log(response.data);
+
+// POST request with JSON body
+const newUser = await accessio.post("https://api.example.com/users", {
+  name: "John Doe",
+  email: "john@example.com",
+});
+console.log(newUser.data);
+```
+
+---
+
+## 📖 API Reference
+
+### Request Methods
+
+```javascript
+accessio(config)
+accessio(url, config?)
+
+accessio.request(config)
+accessio.get(url, config?)
+accessio.delete(url, config?)
+accessio.head(url, config?)
+accessio.options(url, config?)
+accessio.post(url, data?, config?)
+accessio.put(url, data?, config?)
+accessio.patch(url, data?, config?)
+accessio.postForm(url, data?, config?)
+accessio.putForm(url, data?, config?)
+accessio.patchForm(url, data?, config?)
+accessio.getUri(config)
+```
+
+### Configuration
+
+```javascript
+{
+  // URL path (optional if baseURL is set)
+  url: '/users',
+
+  // HTTP method (default: 'get')
+  method: 'get',
+
+  // Base URL prepended to `url` unless `url` is absolute
+  baseURL: 'https://api.example.com',
+
+  // Request headers
+  headers: {
+    'Authorization': 'Bearer token',
+    'X-Custom-Header': 'value'
+  },
+
+  // URL query parameters
+  params: { page: 1, limit: 10 },
+
+  // Custom params serializer
+  paramsSerializer: (params) => Qs.stringify(params),
+
+  // Request body (for POST, PUT, PATCH)
+  data: { name: 'John' },
+
+  // Timeout in milliseconds (0 = no timeout)
+  timeout: 5000,
+
+  // Expected response type: 'json' | 'text' | 'blob' | 'arraybuffer' | 'stream'
+  responseType: 'json',
+
+  // Include credentials in cross-site requests
+  withCredentials: false,
+
+  // Basic auth (sets Authorization header automatically)
+  auth: { username: 'user', password: 'secret' },
+
+  // Transform functions for request/response data
+  transformRequest: [(data, headers) => { /* ... */ return data; }],
+  transformResponse: [(data) => { /* ... */ return data; }],
+
+  // Automatic retry strategy
+  retry: 3,                // Max retry attempts (default: 0)
+  retryDelay: 1000,        // Base delay in ms, doubles on each attempt (default: 1000)
+  retryCondition: (error) => true,  // Custom retry predicate
+  onRetry: (attempt, error, config) => {},  // Called before each retry
+
+  // Debug logging
+  debug: true,             // Enable request/response debug logger
+
+  // Rate limiting
+  rateLimiter: limiter,    // Rate limiter instance for concurrency control
+
+  // Determine which status codes resolve/reject the promise
+  validateStatus: (status) => status >= 200 && status < 300,
+
+  // AbortSignal for request cancellation
+  signal: controller.signal
+}
+```
+
+### Response Object
+
+```javascript
+{
+  data: {},              // Parsed response body
+  status: 200,           // HTTP status code
+  statusText: 'OK',      // HTTP status message
+  headers: {},           // Response headers (lowercase keys)
+  config: {},            // Request configuration used
+  request: {},           // Underlying fetch Response object
+  duration: 142          // Request duration in milliseconds
+}
+```
+
+---
+
+## 🔧 Creating Instances
+
+```typescript
+import accessio from "accessio";
+
+const api = accessio.create({
+  baseURL: "https://api.example.com",
+  timeout: 10000,
+  headers: {
+    Authorization: "Bearer my-token",
+  },
+});
+
+// All requests will use the instance config
+const users = await api.get("/users");
+const posts = await api.get("/posts", { params: { limit: 5 } });
+```
+
+---
+
+## 🔄 Interceptors
+
+```typescript
+// Request interceptor — runs before every request
+accessio.interceptors.request.use(
+  (config) => {
+    config.headers["Authorization"] = `Bearer ${getToken()}`;
+    return config;
+  },
+  (error) => Promise.reject(error),
+);
+
+// Response interceptor — runs after every response
+accessio.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    // Handle 401 globally
+    if (error.response?.status === 401) {
+      redirectToLogin();
+    }
+    return Promise.reject(error);
+  },
+);
+
+// Conditional interceptor — runs only when the predicate returns true
+accessio.interceptors.request.use(
+  (config) => {
+    /* ... */ return config;
+  },
+  null,
+  { runWhen: (config) => config.method === "post" },
+);
+
+// Remove a single interceptor
+const id = accessio.interceptors.request.use(/* ... */);
+accessio.interceptors.request.eject(id);
+
+// Remove all interceptors
+accessio.interceptors.request.clear();
+```
+
+**Execution order:**
+
+- Request interceptors run in **reverse** order (last added → first executed)
+- Response interceptors run in **normal** order (first added → first executed)
+
+---
+
+## 🛡️ Error Handling
+
+```typescript
+try {
+  await accessio.get("/might-fail");
+} catch (error) {
+  if (accessio.isAccessioError(error)) {
+    if (error.response) {
+      console.log(error.response.status); // 404, 500, etc.
+      console.log(error.response.data); // Response body
+    } else if (error.code === "ERR_NETWORK") {
+      console.log("Network error — no response received");
+    } else if (error.code === "ETIMEDOUT") {
+      console.log("Request timed out");
+    } else if (accessio.isCancel(error)) {
+      console.log("Request was cancelled");
+    }
+
+    console.log(error.config); // Request config
+    console.log(error.message); // Error message
+    console.log(error.toJSON()); // Serializable summary
+  }
+}
+```
+
+### Error Codes
+
+| Code                        | Description                             |
+| --------------------------- | --------------------------------------- |
+| `ERR_BAD_REQUEST`           | 4xx status code                         |
+| `ERR_BAD_RESPONSE`          | 5xx status code                         |
+| `ERR_NETWORK`               | Network error (no response received)    |
+| `ETIMEDOUT`                 | Request timed out                       |
+| `ECONNABORTED`              | Request was aborted                     |
+| `ERR_CANCELED`              | Request was cancelled via `AbortSignal` |
+| `ERR_BAD_OPTION`            | Invalid or missing configuration option |
+| `ERR_BAD_OPTION_VALUE`      | Invalid configuration option value      |
+| `ERR_INVALID_URL`           | The provided URL is invalid             |
+| `ERR_FR_TOO_MANY_REDIRECTS` | Too many redirects                      |
+| `ERR_NOT_SUPPORT`           | Feature not supported in environment    |
+
+---
+
+## 🔀 Concurrent Requests
+
+```javascript
+const [users, posts] = await accessio.all([
+  accessio.get("/users"),
+  accessio.get("/posts"),
+]);
+
+// Or with the spread helper (deprecated — use modern spread syntax instead)
+accessio.all([accessio.get("/users"), accessio.get("/posts")]).then(
+  accessio.spread((users, posts) => {
+    console.log(users.data, posts.data);
+  }),
+);
+```
+
+---
+
+## ❌ Cancellation
+
+```javascript
+const controller = new AbortController();
+
+accessio
+  .get("/slow-endpoint", {
+    signal: controller.signal,
+  })
+  .catch((error) => {
+    if (accessio.isCancel(error)) {
+      console.log("Request cancelled:", error.message);
+    }
+  });
+
+// Cancel the request
+controller.abort();
+```
+
+---
+
+## 🔧 Transform Request / Response
+
+```javascript
+const api = accessio.create({
+  transformRequest: [
+    (data, headers) => {
+      // Add a timestamp to every outgoing body
+      if (data && typeof data === "object") {
+        data.timestamp = Date.now();
+      }
+      return JSON.stringify(data);
+    },
+  ],
+  transformResponse: [
+    (data) => {
+      if (typeof data === "string") {
+        try {
+          return JSON.parse(data);
+        } catch {}
+      }
+      return data;
+    },
+    (data) => {
+      // Unwrap a { data: ... } envelope
+      return data?.data ?? data;
+    },
+  ],
+});
+```
+
+---
+
+## ♻️ Advanced Features
+
+### Automatic Retry
+
+accessio supports configurable retries with exponential backoff and ±25% jitter to prevent thundering herd.
+
+```javascript
+const response = await accessio.get("/flaky-api", {
+  retry: 3, // Retry up to 3 times
+  retryDelay: 1000, // Base delay — doubles on each attempt: 1s, 2s, 4s
+
+  // Optional: custom condition (default: network errors + 5xx)
+  retryCondition: (error) => error.response?.status === 503,
+
+  // Optional: callback before each retry
+  onRetry: (attempt, error, config) => {
+    console.log(`Retry attempt #${attempt} after: ${error.message}`);
+  },
+});
+```
+
+The default `retryCondition` retries on:
+
+- `ERR_NETWORK` — no response received
+- `ETIMEDOUT` — request timed out
+- 5xx server errors
+- Does **not** retry on `ERR_CANCELED` or 4xx client errors
+
+### Rate Limiting
+
+Control the maximum number of concurrent in-flight requests.
+
+#### Option 1: Built-in config integration (recommended)
+
+```javascript
+import accessio, { createRateLimiter } from "accessio";
+
+const limiter = createRateLimiter(5); // max 5 concurrent requests
+
+// Pass the limiter directly in the request config
+const response = await accessio.get("/api/data", { rateLimiter: limiter });
+
+// Or set it as an instance default
+const api = accessio.create({ rateLimiter: limiter });
+const users = await api.get("/users");
+```
+
+#### Option 2: Manual acquire / release
+
+```javascript
+import { createRateLimiter } from "accessio";
+
+const limiter = createRateLimiter(5);
+
+await limiter.acquire();
+try {
+  const res = await accessio.get("/api/data");
+} finally {
+  limiter.release();
+}
+
+// Inspect state
+console.log(limiter.active); // Currently running requests
+console.log(limiter.pending); // Requests waiting in queue
+
+// Cleanup on navigation / component unmount — rejects all queued promises
+limiter.destroy();
+console.log(limiter.destroyed); // true
+```
+
+### Debug Logging
+
+Enable `debug: true` on an instance or a single request to get structured console output.
+
+```javascript
+const api = accessio.create({ debug: true });
+
+// 🐦‍⬛ [accessio] → GET https://api.example.com/users
+//    Params: {"page":1}
+//    Timeout: 5000ms
+// 🐦‍⬛ [accessio] ← ✅ 200 OK (142ms)
+//    Size: ~3.2 KB
+
+// Or enable per-request only
+await accessio.get("/debug-this", { debug: true });
+```
+
+---
+
+## 📥 Imports
+
+### ESM (recommended)
+
+```typescript
+import accessio from "accessio";
+import {
+  createRateLimiter,
+  AccessioError,
+  mergeConfig,
+  buildURL,
+  logRequest,
+  logResponse,
+  logError,
+} from "accessio";
+```
+
+### CommonJS
+
+```typescript
+const accessio = require("accessio");
+const { createRateLimiter } = require("accessio");
+```
+
+### Sub-path imports
+
+```javascript
+// Import only what you need
+import { createRateLimiter } from "accessio/helpers/rateLimiter";
+import { logRequest, logResponse, logError } from "accessio/helpers/debug";
+import { buildURL } from "accessio/core/buildURL";
+import { mergeConfig } from "accessio/core/mergeConfig";
+import { dispatchRequest } from "accessio/core/request";
+import { retryRequest } from "accessio/core/retry";
+import { parseHeaders } from "accessio/helpers/parseHeaders";
+import { settle } from "accessio/helpers/settle";
+import { transformData } from "accessio/helpers/transformData";
+```
+
+---
+
+## 📚 Documentation
+
+| Document                          | Description                                 |
+| --------------------------------- | ------------------------------------------- |
+| [CHANGELOG](./CHANGELOG.md)       | Version history and release notes           |
+| [CONTRIBUTING](./CONTRIBUTING.md) | Guide for contributors                      |
+| [SECURITY](./SECURITY.md)         | Security policy and vulnerability reporting |
+| [CONTRIBUTORS](./CONTRIBUTORS.md) | Project contributors                        |
+
+## 📝 Author
+
+**Salvatore Corvaglia**
+
+- GitHub: [@salvatorecorvaglia](https://github.com/salvatorecorvaglia)

package/cjs/accessio.cjs

@@ -0,0 +1,208 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var accessio_exports = {};
+__export(accessio_exports, {
+  Accessio: () => Accessio,
+  default: () => accessio_default
+});
+module.exports = __toCommonJS(accessio_exports);
+var import_interceptorManager = __toESM(require("./interceptors/interceptorManager"), 1);
+var import_accessioError = __toESM(require("./core/accessioError"), 1);
+var import_mergeConfig = __toESM(require("./core/mergeConfig"), 1);
+var import_request = __toESM(require("./core/request"), 1);
+var import_buildURL = __toESM(require("./core/buildURL"), 1);
+var import_retry = __toESM(require("./core/retry"), 1);
+var import_debug = require("./helpers/debug");
+var import_rateLimiter = require("./helpers/rateLimiter");
+class Accessio {
+  defaults;
+  interceptors;
+  constructor(instanceConfig = {}) {
+    this.defaults = instanceConfig;
+    this.interceptors = {
+      request: new import_interceptorManager.default(),
+      response: new import_interceptorManager.default()
+    };
+  }
+  request(configOrUrl, config) {
+    if (typeof configOrUrl === "string") {
+      config = { ...config, url: configOrUrl };
+    } else {
+      config = configOrUrl ? { ...configOrUrl } : {};
+    }
+    const mergedConfig = (0, import_mergeConfig.default)(this.defaults, config);
+    mergedConfig.method = (mergedConfig.method || "get").toLowerCase();
+    if (!mergedConfig.url && !mergedConfig.baseURL) {
+      throw new import_accessioError.default(
+        "Request URL is required. Provide a `url` or `baseURL` in the config.",
+        import_accessioError.default.ERR_BAD_OPTION,
+        mergedConfig,
+        null,
+        null
+      );
+    }
+    const requestInterceptors = [];
+    const responseInterceptors = [];
+    this.interceptors.request.forEach((interceptor) => {
+      if (interceptor.runWhen && !interceptor.runWhen(mergedConfig)) {
+        return;
+      }
+      requestInterceptors.unshift(interceptor);
+    });
+    this.interceptors.response.forEach((interceptor) => {
+      responseInterceptors.push(interceptor);
+    });
+    let promise = Promise.resolve(mergedConfig);
+    for (const interceptor of requestInterceptors) {
+      promise = promise.then(
+        (value) => {
+          if (interceptor.fulfilled) {
+            return interceptor.fulfilled(value);
+          }
+          return value;
+        },
+        interceptor.rejected
+      );
+    }
+    promise = promise.then((cfg) => {
+      const fullUrl = (0, import_buildURL.default)(
+        cfg.url ?? "",
+        cfg.baseURL,
+        cfg.params,
+        cfg.paramsSerializer
+      );
+      (0, import_debug.logRequest)(cfg, fullUrl);
+      const enrichedCfg = fullUrl !== (cfg.url || "") ? { ...cfg, _builtUrl: fullUrl } : cfg;
+      const dispatchFn = cfg.rateLimiter ? (config2) => (0, import_rateLimiter.rateLimitedRequest)(import_request.default, config2.rateLimiter, config2) : import_request.default;
+      return (0, import_retry.default)(dispatchFn, enrichedCfg);
+    });
+    promise = promise.then(
+      (value) => {
+        (0, import_debug.logResponse)(value);
+        return value;
+      },
+      (error) => {
+        (0, import_debug.logError)(error, mergedConfig);
+        throw error;
+      }
+    );
+    for (const interceptor of responseInterceptors) {
+      promise = promise.then(
+        (value) => {
+          if (interceptor.fulfilled) {
+            return interceptor.fulfilled(value);
+          }
+          return value;
+        },
+        interceptor.rejected
+      );
+    }
+    return promise;
+  }
+  getUri(config) {
+    const merged = (0, import_mergeConfig.default)(this.defaults, config);
+    return (0, import_buildURL.default)(
+      merged.url ?? "",
+      merged.baseURL,
+      merged.params,
+      merged.paramsSerializer
+    );
+  }
+  get(url, config) {
+    return this.request(
+      (0, import_mergeConfig.default)(config || {}, { method: "get", url })
+    );
+  }
+  delete(url, config) {
+    return this.request(
+      (0, import_mergeConfig.default)(config || {}, { method: "delete", url })
+    );
+  }
+  head(url, config) {
+    return this.request(
+      (0, import_mergeConfig.default)(config || {}, { method: "head", url })
+    );
+  }
+  options(url, config) {
+    return this.request(
+      (0, import_mergeConfig.default)(config || {}, { method: "options", url })
+    );
+  }
+  post(url, data, config) {
+    return this.request(
+      (0, import_mergeConfig.default)(config || {}, { method: "post", url, data })
+    );
+  }
+  put(url, data, config) {
+    return this.request(
+      (0, import_mergeConfig.default)(config || {}, { method: "put", url, data })
+    );
+  }
+  patch(url, data, config) {
+    return this.request(
+      (0, import_mergeConfig.default)(config || {}, { method: "patch", url, data })
+    );
+  }
+  postForm(url, data, config) {
+    return this.request(
+      (0, import_mergeConfig.default)(config || {}, {
+        method: "post",
+        url,
+        data,
+        headers: { "Content-Type": "multipart/form-data" }
+      })
+    );
+  }
+  putForm(url, data, config) {
+    return this.request(
+      (0, import_mergeConfig.default)(config || {}, {
+        method: "put",
+        url,
+        data,
+        headers: { "Content-Type": "multipart/form-data" }
+      })
+    );
+  }
+  patchForm(url, data, config) {
+    return this.request(
+      (0, import_mergeConfig.default)(config || {}, {
+        method: "patch",
+        url,
+        data,
+        headers: { "Content-Type": "multipart/form-data" }
+      })
+    );
+  }
+}
+var accessio_default = Accessio;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Accessio
+});
+//# sourceMappingURL=accessio.cjs.map