aziosxjs 0.4.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Azeem Ali
+
+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

@@ -1,351 +1,176 @@
 # Aziosxjs
 
-A modern, lightweight HTTP client for Node.js designed for performance, extensibility, and clarity.
+[![npm version](https://badge.fury.io/js/aziosxjs.svg)](https://badge.fury.io/js/aziosxjs) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/) [![Node.js](https://img.shields.io/badge/Node.js-14+-green.svg)](https://nodejs.org/)
 
-Aziosxjs provides a clean API for making HTTP requests while exposing a modular request pipeline architecture.
-It is built directly on Node.js low-level `http` and `https` modules to demonstrate how production-grade HTTP clients work internally.
-
-The goal of this project is to provide a simple but powerful HTTP client that supports advanced features such as retries, caching, request deduplication, and rate limiting.
+A lightweight, modular HTTP client with a clean API and a composable request pipeline.
 
 ---
 
-# Features
-
-### Core HTTP
-
-* Promise-based HTTP requests
-* Support for GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
-* Automatic JSON parsing
-* Automatic request body serialization
-* Query parameter serialization
-
-### Request Pipeline
-
-* Request interceptors
-* Response interceptors
-* Structured error system
-* AbortController cancellation support
-
-### Performance Features
-
-* Automatic retry system
-* Exponential backoff strategy
-* Request deduplication (prevents duplicate concurrent requests)
-* Response caching
-* Built-in rate limiting
-
-### Developer Experience
+## Table of Contents
 
-* TypeScript support
-* Modular architecture
-* Lightweight dependency-free implementation
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [Plugins & Middleware](#plugins--middleware)
+- [Performance Features](#performance-features)
+- [Error Handling](#error-handling)
+- [Running Tests](#running-tests)
+- [Contributing](#contributing)
+- [License](#license)
 
 ---
 
-# Installation
+## Installation
 
-```bash id="x0c2qz"
+```bash
 npm install aziosxjs
 ```
 
 ---
 
-# Quick Example
+## Quick Start
 
-```javascript id="xgqz2e"
+```js
 import azios from "aziosxjs";
 
-async function getUsers() {
-  const response = await azios.get(
-    "https://jsonplaceholder.typicode.com/users"
-  );
-
-  console.log(response.data);
-}
-
-getUsers();
+const response = await azios.get("https://jsonplaceholder.typicode.com/users/1");
+console.log(response.data);
 ```
 
 ---
 
-# Basic Usage
-
-## GET Request
+## Core Concepts
 
-```javascript id="q2s48a"
-const res = await azios.get("https://api.example.com/users");
+### HTTP Methods
 
-console.log(res.data);
+```js
+await azios.get("/users");
+await azios.post("/users", { name: "Jane" });
+await azios.put("/users/1", { name: "Jane" });
+await azios.delete("/users/1");
 ```
 
----
-
-## POST Request
+### Configuration
 
-```javascript id="ys8fr0"
-const res = await azios.post(
-  "https://api.example.com/login",
-  {
-    username: "user",
-    password: "password"
-  }
-);
-
-console.log(res.data);
+```js
+const response = await azios.request({
+  url: "/users",
+  method: "GET",
+  baseURL: "https://api.example.com",
+  params: { page: 1, limit: 10 },
+  headers: { Authorization: "Bearer TOKEN" },
+  timeout: 5000,
+});
 ```
 
----
-
-# Query Parameters
-
-Aziosxjs automatically serializes query parameters.
-
-```javascript id="6e6w1q"
-const res = await azios.get(
-  "https://jsonplaceholder.typicode.com/posts",
-  {
-    params: { _limit: 2 }
-  }
-);
+### Instances
 
-console.log(res.data);
-```
-
-Generated URL:
+```js
+import { createInstance } from "aziosxjs";
 
-```id="2dq3rc"
-/posts?_limit=2
+const api = createInstance({ baseURL: "https://api.example.com" });
+await api.get("/users");
 ```
 
 ---
 
-# Interceptors
-
-Interceptors allow you to modify requests or responses globally.
-
-## Request Interceptor
+## Plugins & Middleware
 
-```javascript id="o7j8rz"
-azios.interceptors.request.use(config => {
-  console.log("Request intercepted");
+### Plugin System
 
-  if (!config.headers) config.headers = {};
-  config.headers["x-client"] = "aziosxjs";
+Plugins provide a clean way to extend Aziosxjs behavior.
 
-  return config;
-});
-```
-
----
+```js
+import type { AziosPlugin } from "aziosxjs";
 
-## Response Interceptor
+const authPlugin: AziosPlugin = {
+  name: "auth",
+  version: "1.0.0",
+  hooks: {
+    beforeRequest: (config) => ({
+      ...config,
+      headers: { ...config.headers, Authorization: "Bearer TOKEN" },
+    }),
+  },
+};
 
-```javascript id="w7r0uj"
-azios.interceptors.response.use(response => {
-  console.log("Response intercepted");
-  return response;
-});
+await azios.installPlugin(authPlugin);
 ```
 
----
-
-# Request Cancellation
+### Middleware
 
-Requests can be cancelled using `AbortController`.
+Middleware runs in sequence and can modify the request/response pipeline.
 
-```javascript id="68f4s3"
-const controller = new AbortController();
+```js
+import type { AziosMiddleware } from "aziosxjs";
 
-azios.get(
-  "https://jsonplaceholder.typicode.com/users",
-  { signal: controller.signal }
-);
+const logger: AziosMiddleware = async (config, next) => {
+  console.log("→", config.method, config.url);
+  const res = await next();
+  console.log("←", res.status);
+  return res;
+};
 
-controller.abort();
-```
-
-If aborted, Aziosxjs throws an error with code:
-
-```id="m5ktg3"
-ABORTED
+azios.use(logger);
 ```
 
 ---
 
-# Retry System
+## Performance Features
 
-Aziosxjs can automatically retry failed requests.
+### Retry + Backoff
 
-```javascript id="zwdg7p"
-await azios.get("https://api.example.com/users", {
-  retry: 3
-});
+```js
+await azios.get("/unstable", { retry: 3, retryDelay: 500 });
 ```
 
-Retries use **exponential backoff** to avoid overwhelming servers.
-
----
+### Deduplication
 
-# Response Caching
+Identical concurrent requests share the same network call.
 
-Responses can be cached in memory.
+### Caching
 
-```javascript id="hjbrgx"
-await azios.get(
-  "https://api.example.com/users",
-  { cache: true }
-);
+```js
+await azios.get("/users", { cache: true, cacheTTL: 5000 });
 ```
 
-Subsequent requests may return cached responses instantly.
-
----
-
-# Rate Limiting
+### Rate Limiting
 
-Control the number of concurrent requests.
-
-```javascript id="m2l4x9"
-await azios.get(
-  "https://api.example.com/users",
-  { rateLimit: 3 }
-);
+```js
+await azios.get("/users", { rateLimit: 5 });
 ```
 
-Only 3 requests will execute simultaneously.
-
 ---
 
-# Error Handling
+## Error Handling
 
-Aziosxjs returns standardized error objects.
+Aziosxjs throws `AziosError` instances with structured metadata.
 
-```javascript id="n2d3kr"
+```js
 try {
-  await azios.get("https://invalid-url.test");
-} catch (error) {
-  console.log(error.name); // AziosError
-  console.log(error.code); // NETWORK_ERROR
+  await azios.get("/404");
+} catch (err) {
+  console.log(err.code, err.message);
 }
 ```
 
-This makes debugging significantly easier.
-
 ---
 
-# Request Pipeline Architecture
-
-Aziosxjs follows a modular pipeline design.
-
-```id="m2b3ux"
-User Code
-   ↓
-Azios Instance
-   ↓
-Request Interceptors
-   ↓
-Retry Engine
-   ↓
-Rate Limiter
-   ↓
-dispatchRequest (HTTP engine)
-   ↓
-Node.js http / https
-   ↓
-Response Interceptors
-   ↓
-Return Response
-```
-
----
+## Running Tests
 
-# Project Structure
-
-```id="v2z3go"
-src
- ├── core
- │    ├── Azios.ts
- │    ├── createInstance.ts
- │    ├── dispatchRequest.ts
- │    └── requestStore.ts
- │
- ├── cache
- │    └── memoryCache.ts
- │
- ├── rateLimiter
- │    └── rateLimiter.ts
- │
- ├── interceptors
- │    └── InterceptorManager.ts
- │
- ├── errors
- │    └── AziosError.ts
- │
- ├── helpers
- │    └── buildURL.ts
- │
- ├── types
- │    ├── config.ts
- │    ├── request.ts
- │    └── response.ts
- │
- └── index.ts
+```bash
+npm test
 ```
 
 ---
 
-# Version Roadmap
-
-### v0.1
-
-* Core HTTP client
-* Instances
-* JSON handling
-* Request configuration
+## Contributing
 
-### v0.2
-
-* Interceptor pipeline
-* Structured error system
-* Request cancellation
-* Query parameter serialization
-
-### v0.3
-
-* Retry mechanism
-* Exponential backoff
-* Request deduplication
-
-### v0.4
-
-* Response caching
-* Rate limiting
-
-### Planned
-
-* Plugin system
-* Middleware pipeline
-* Advanced TypeScript inference
-* Universal runtime support (Node, Browser, Edge)
+Contributions are welcome. Please open an issue or pull request.
 
 ---
 
-# Contributing
-
-Contributions are welcome.
-
-1. Fork the repository
-2. Create a feature branch
-3. Submit a pull request
-
----
-
-# Author
-
-Azeem Ali
-
----
+## License
 
-# License
+MIT © 2026 Azeem Ali
 
-MIT

package/dist/cache/memoryCache.d.ts

@@ -0,0 +1,4 @@
+export declare function getCache(key: string): any;
+export declare function setCache(key: string, value: any, ttl?: number): void;
+export declare function clearCache(key: string): void;
+export declare function clearAllCache(): void;

package/dist/cache/memoryCache.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCache = getCache;
+exports.setCache = setCache;
+exports.clearCache = clearCache;
+exports.clearAllCache = clearAllCache;
+const cache = new Map();
+function getCache(key) {
+    const entry = cache.get(key);
+    if (!entry)
+        return null;
+    // remove expired cache
+    if (Date.now() > entry.expiry) {
+        cache.delete(key);
+        return null;
+    }
+    return entry.data;
+}
+function setCache(key, value, ttl = 5000) {
+    const expiry = Date.now() + ttl;
+    cache.set(key, {
+        data: value,
+        expiry
+    });
+}
+function clearCache(key) {
+    cache.delete(key);
+}
+function clearAllCache() {
+    cache.clear();
+}
+//# sourceMappingURL=memoryCache.js.map

package/dist/cache/memoryCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryCache.js","sourceRoot":"","sources":["../../src/cache/memoryCache.ts"],"names":[],"mappings":";;AAOA,4BAcC;AAED,4BAaC;AAED,gCAEC;AAED,sCAEC;AAvCD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAA;AAE3C,SAAgB,QAAQ,CAAC,GAAW;IAElC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAE5B,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IAEvB,uBAAuB;IACvB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAC9B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACjB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAA;AAEnB,CAAC;AAED,SAAgB,QAAQ,CACtB,GAAW,EACX,KAAU,EACV,MAAc,IAAI;IAGlB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAA;IAE/B,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;QACb,IAAI,EAAE,KAAK;QACX,MAAM;KACP,CAAC,CAAA;AAEJ,CAAC;AAED,SAAgB,UAAU,CAAC,GAAW;IACpC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;AACnB,CAAC;AAED,SAAgB,aAAa;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAA;AACf,CAAC"}

package/dist/core/Azios.d.ts

@@ -1,13 +1,43 @@
 import { AziosRequestConfig } from "../types/config";
+import type { AziosPlugin } from "../types/plugin";
 import InterceptorManager from "../interceptors/InterceptorManager";
+import PluginManager from "../plugins/pluginManager";
+import MiddlewareManager from "../middleware/middlewareManager";
+/**
+ * Core Azios HTTP client class
+ * Production-grade implementation with plugin system, middleware, and interceptors
+ */
 export default class Azios {
     defaults: AziosRequestConfig;
     interceptors: {
         request: InterceptorManager<AziosRequestConfig>;
         response: InterceptorManager<any>;
     };
+    middlewares: MiddlewareManager;
+    plugins: PluginManager;
     constructor(config: AziosRequestConfig);
-    request(config: AziosRequestConfig): Promise<import("../types/response").AziosResponse<any>>;
-    get(url: string, config?: AziosRequestConfig): Promise<import("../types/response").AziosResponse<any>>;
-    post(url: string, data?: any, config?: AziosRequestConfig): Promise<import("../types/response").AziosResponse<any>>;
+    /**
+     * Register middleware using Koa-style middleware pattern
+     */
+    use(fn: any): void;
+    /**
+     * Install a plugin into this instance
+     * @throws Error if plugin is already installed or installation fails
+     */
+    installPlugin(plugin: AziosPlugin): Promise<void>;
+    /**
+     * Uninstall a plugin by name
+     */
+    uninstallPlugin(pluginName: string): Promise<void>;
+    /**
+     * Core request method - central request pipeline
+     */
+    request(config: AziosRequestConfig): Promise<any>;
+    get(url: string, config?: AziosRequestConfig): Promise<any>;
+    post(url: string, data?: any, config?: AziosRequestConfig): Promise<any>;
+    put(url: string, data?: any, config?: AziosRequestConfig): Promise<any>;
+    patch(url: string, data?: any, config?: AziosRequestConfig): Promise<any>;
+    delete(url: string, config?: AziosRequestConfig): Promise<any>;
+    head(url: string, config?: AziosRequestConfig): Promise<any>;
+    options(url: string, config?: AziosRequestConfig): Promise<any>;
 }

package/dist/core/Azios.js

@@ -5,6 +5,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const dispatchRequest_1 = __importDefault(require("./dispatchRequest"));
 const InterceptorManager_1 = __importDefault(require("../interceptors/InterceptorManager"));
+const pluginManager_1 = __importDefault(require("../plugins/pluginManager"));
+const middlewareManager_1 = __importDefault(require("../middleware/middlewareManager"));
+const compose_1 = require("../middleware/compose");
+/**
+ * Core Azios HTTP client class
+ * Production-grade implementation with plugin system, middleware, and interceptors
+ */
 class Azios {
     constructor(config) {
         this.defaults = config;
@@ -12,11 +19,84 @@ class Azios {
             request: new InterceptorManager_1.default(),
             response: new InterceptorManager_1.default()
         };
+        this.middlewares = new middlewareManager_1.default();
+        this.plugins = new pluginManager_1.default();
     }
-    request(config) {
+    /**
+     * Register middleware using Koa-style middleware pattern
+     */
+    use(fn) {
+        this.middlewares.use(fn);
+    }
+    /**
+     * Install a plugin into this instance
+     * @throws Error if plugin is already installed or installation fails
+     */
+    async installPlugin(plugin) {
+        await this.plugins.install(plugin, this);
+    }
+    /**
+     * Uninstall a plugin by name
+     */
+    async uninstallPlugin(pluginName) {
+        await this.plugins.uninstall(pluginName, this);
+    }
+    /**
+     * Core request method - central request pipeline
+     */
+    async request(config) {
         config = { ...this.defaults, ...config };
-        return (0, dispatchRequest_1.default)(config);
+        // -------------------------
+        // PLUGIN: PRE-REQUEST HOOKS
+        // -------------------------
+        config = await this.plugins.executeBeforeRequestHooks(config);
+        // -------------------------
+        // MIDDLEWARE PIPELINE
+        // -------------------------
+        const context = { config };
+        const fn = (0, compose_1.compose)(this.middlewares.middlewares);
+        await fn(context);
+        config = context.config;
+        // -------------------------
+        // INTERCEPTOR PIPELINE
+        // -------------------------
+        const chain = [];
+        // Request interceptors (reverse order)
+        this.interceptors.request.forEach(interceptor => {
+            chain.unshift(interceptor.fulfilled, interceptor.rejected);
+        });
+        // Main dispatch
+        chain.push(dispatchRequest_1.default, undefined);
+        // Response interceptors (normal order)
+        this.interceptors.response.forEach(interceptor => {
+            chain.push(interceptor.fulfilled, interceptor.rejected);
+        });
+        let promise = Promise.resolve(config);
+        while (chain.length) {
+            const fulfilled = chain.shift();
+            const rejected = chain.shift();
+            promise = promise.then(fulfilled, rejected);
+        }
+        try {
+            const response = await promise;
+            // -------------------------
+            // PLUGIN: POST-RESPONSE HOOKS
+            // -------------------------
+            return await this.plugins.executeAfterResponseHooks(response);
+        }
+        catch (error) {
+            // -------------------------
+            // PLUGIN: ERROR HOOKS
+            // -------------------------
+            if (error instanceof Error) {
+                throw await this.plugins.executeOnErrorHooks(error);
+            }
+            throw error;
+        }
     }
+    // =========================================
+    // HTTP METHODS
+    // =========================================
     get(url, config) {
         return this.request({
             ...config,
@@ -32,6 +112,43 @@ class Azios {
             data
         });
     }
+    put(url, data, config) {
+        return this.request({
+            ...config,
+            method: "PUT",
+            url,
+            data
+        });
+    }
+    patch(url, data, config) {
+        return this.request({
+            ...config,
+            method: "PATCH",
+            url,
+            data
+        });
+    }
+    delete(url, config) {
+        return this.request({
+            ...config,
+            method: "DELETE",
+            url
+        });
+    }
+    head(url, config) {
+        return this.request({
+            ...config,
+            method: "HEAD",
+            url
+        });
+    }
+    options(url, config) {
+        return this.request({
+            ...config,
+            method: "OPTIONS",
+            url
+        });
+    }
 }
 exports.default = Azios;
 //# sourceMappingURL=Azios.js.map