@winxs/wind 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Winxs
+
+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,187 @@
+# 🌬️ Wind — @winxs/wind
+
+[![npm version](https://img.shields.io/npm/v/@winxs/wind)](https://www.npmjs.com/package/@winxs/wind)
+[![npm downloads](https://img.shields.io/npm/dm/@winxs/wind)](https://www.npmjs.com/package/@winxs/wind)
+[![license](https://img.shields.io/npm/l/@winxs/wind)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue)](https://www.typescriptlang.org/)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@winxs/wind)](https://bundlephobia.com/package/@winxs/wind)
+
+**Modern HTTP orchestration client for JavaScript & TypeScript**
+
+> Axios helps you make requests.  
+> **Wind helps you manage flows.**
+
+**Wind** is a modern HTTP orchestration client for JavaScript and TypeScript.
+
+> Axios helps you make requests.  
+> **Wind helps you manage flows.**
+
+Wind is built for **real-world APIs** — pagination, retries, batching, circuit breakers, and failure-safe third-party integrations.
+
+---
+
+## ✨ Why Wind?
+
+Most HTTP clients stop at `request → response`.
+
+In real systems you also need:
+
+- Pagination without writing loops
+- Safe retries
+- Partial-failure batch calls
+- Protection against unstable third-party APIs
+- Worker & SSR-friendly (no global state, isolated clients)
+> ⚠️ For SSR or workers, always create a new client using `wind()` or `windClient`.
+
+
+**Wind provides these as first-class primitives.**
+
+---
+
+## 🚀 Features
+
+- ⚡ **Simple API** (Axios-style defaults)
+- 🔁 **Built-in retry support**
+- 🔌 **Circuit breaker** for failing APIs
+- 📄 **Pagination as async iterators**
+- 📦 **Batch requests with partial failures**
+- 🧵 **Worker & SSR safe** (no global mutation)
+- 🪶 **Lightweight & dependency-minimal**
+
+### 🌍 Runtime Environments
+
+Wind is designed to run in:
+
+- Browsers
+- Node.js (18+)
+- Workers / Edge runtimes
+
+> Wind does not rely on global mutable state,
+making it safe for concurrent and isolated environments.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @winxs/wind
+```
+## 🧩 Usage
+### 1️⃣ Quick (Axios-style)
+```ts
+
+import wind from "@winxs/wind";
+const users = await wind.get("/users");
+The default wind client is shared.
+For production, workers, or multiple APIs — prefer the factory or class.
+```
+
+### 2️⃣ Recommended: Factory API
+```ts
+import { wind } from "@winxs/wind";
+
+const api = wind({
+  baseURL: "https://api.example.com",
+});
+
+const users = await api.get("/users");
+```
+### 3️⃣ Advanced: Isolated Client
+```ts
+import { windClient } from "@winxs/wind";
+
+const github = new windClient("https://api.github.com");
+
+const repos = await github.get("/users/octocat/repos");
+```
+### 🔁 Pagination (No Loops)
+#### ❌ Traditional approach
+```ts
+let page = 1;
+while (true) {
+  const res = await fetch(`/users?page=${page}`);
+  if (!res.length) break;
+  page++;
+}
+```
+### ✅ Wind way
+```ts
+for await (const page of api.paginate("/users")) {
+  console.log(page);
+}
+```
+* Lazy
+* Memory-safe
+* Failure-aware
+
+### 📦 Batch Requests (Promise.all++)
+#### ❌ Traditional
+```ts
+await Promise.all([
+  fetch("/a"),
+  fetch("/b"),
+]);
+```
+#### ✅ Wind
+```ts
+const { results, errors } = await api.batch(
+  [
+    () => api.get("/a"),
+    () => api.get("/b"),
+  ],
+  { concurrency: 2 }
+);
+```
+* Controlled concurrency
+* Partial success support
+* No global failures
+
+### 🔌 Circuit Breaker
+1. Wind protects your system from unstable APIs.
+2. Trips on network failures
+3. Trips on 5xx responses
+4. Trips on rate-limits (429)
+5. Ignores 4xx & validation errors
+
+```ts
+await api.get("/third-party"); // auto-protected
+```
+* When the circuit is open, requests fail fast instead of cascading failures.
+
+### 🔁 Retry Support
+```ts
+await api.get("/unstable", {
+  retry: {
+    attempts: 3,
+  },
+});
+```
+* Retry happens before circuit breaker evaluation.
+
+### 🔄 Axios → Wind Migration
+#### Axios
+```ts
+import axios from "axios";
+axios.get("/users");
+```
+#### Wind
+```ts
+import wind from "@winxs/wind";
+wind.get("/users");
+```
+#### Axios Instance
+```ts
+const api = axios.create({ baseURL });
+```
+#### Wind Factory
+```ts
+const api = wind({ baseURL });
+```
+#### Axios Pagination
+```ts
+// manual looping
+```
+#### Wind Pagination
+```ts
+for await (const page of api.paginate("/users")) {}
+```

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+type ErrorType = "NETWORK" | "TIMEOUT" | "RATE_LIMIT" | "SERVER" | "CLIENT" | "SCHEMA" | "UNKNOWN";
+
+declare class HttpError extends Error {
+    type: ErrorType;
+    status?: number;
+    response?: any;
+    constructor(message: string, type: ErrorType, status?: number, response?: any);
+}
+
+interface RetryOptions {
+    attemps: number;
+    backOffMs?: number;
+    retryOn?: ErrorType[];
+}
+
+interface RequestOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: any;
+    timeoutMS?: number;
+    retry?: RetryOptions;
+}
+
+interface PaginationConfig {
+    pageParam?: string;
+    startPage?: number;
+    stopOnEmpty?: boolean;
+    options?: RequestOptions;
+}
+
+interface BatchOptions {
+    concurrency?: number;
+    failFast?: boolean;
+}
+
+declare class windClient {
+    private baseURL;
+    private breaker;
+    constructor(baseURL?: string);
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, body: any, options?: RequestOptions): Promise<T>;
+    paginate<T>(path: string, config?: PaginationConfig): AsyncGenerator<T, any, any>;
+    batch<T>(tasks: (() => Promise<T>)[], options?: BatchOptions): Promise<{
+        results: T[];
+        errors: HttpError[];
+    }>;
+    private shouldTripBreaker;
+}
+declare function wind(config?: {
+    baseURL?: string;
+}): windClient;
+declare const defaultWind: windClient;
+
+export { defaultWind as default, wind, windClient };

package/dist/index.js

@@ -0,0 +1,186 @@
+// src/Utility/HttpError.ts
+var HttpError = class extends Error {
+  constructor(message, type, status, response) {
+    super(message);
+    this.type = type;
+    this.status = status;
+    this.response = response;
+  }
+};
+function classifyError(err) {
+  if (err instanceof HttpError) return err;
+  if (err.name === "AbortError") return new HttpError("Request Timed Out", "TIMEOUT");
+  if (err.status) {
+    if (err.status === 429) return new HttpError("Rate limited", "RATE_LIMIT", 429);
+    if (err.status >= 500) return new HttpError("Server error", "SERVER", err.status);
+    if (err.status >= 400) return new HttpError("Client error", "CLIENT", err.status);
+  }
+  return new HttpError(err.message || "Unknown error", "UNKNOWN");
+}
+
+// src/Utility/coreRequest.ts
+async function coreRequest(url, options) {
+  const controller = new AbortController();
+  if (options.timeoutMS) {
+    setTimeout(() => controller.abort(), options.timeoutMS);
+  }
+  const res = await fetch(url, {
+    method: options.method || "GET",
+    headers: {
+      ...options.headers
+    },
+    body: options.body ? JSON.stringify(options.body) : void 0,
+    signal: controller.signal
+  });
+  let data = null;
+  let text = null;
+  try {
+    text = await res.text();
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    throw new HttpError("Invalid JSON Response", "SCHEMA", res.status, text);
+  }
+  if (!res.ok) {
+    throw new HttpError("HTTP Error", "CLIENT", res.status, data);
+  }
+  return data;
+}
+
+// src/Utility/Retry.ts
+async function withRetry(fn, options) {
+  const {
+    attemps,
+    backOffMs = 300,
+    //5 mins
+    retryOn = ["NETWORK", "TIMEOUT", "RATE_LIMIT", "SERVER"]
+  } = options;
+  let lastError;
+  for (let i = 0; i < attemps; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      let classified = classifyError(err);
+      lastError = classified;
+      if (!retryOn.includes(classified.type)) throw classified;
+      await new Promise((r) => setTimeout(r, backOffMs * (i + 1)));
+    }
+  }
+  throw lastError;
+}
+
+// src/Utility/CircuitBreaker.ts
+var CircuitBreaker = class {
+  constructor(threshold = 5, timeoutMs = 1e4) {
+    this.threshold = threshold;
+    this.timeoutMs = timeoutMs;
+    this.failures = 0;
+    this.lastFailure = 0;
+  }
+  canRequest() {
+    if (this.failures < this.threshold) return true;
+    return Date.now() - this.lastFailure > this.timeoutMs;
+  }
+  success() {
+    this.failures = 0;
+  }
+  failure() {
+    this.failures++;
+    this.lastFailure = Date.now();
+  }
+};
+
+// src/Helper/Pagination.ts
+async function* paginate(fetcher, path, config = {}) {
+  const pageParam = config.pageParam ?? "page";
+  let page = config.startPage ?? 1;
+  while (true) {
+    const data = await fetcher(
+      `${path}?${pageParam}=${page}`,
+      config.options
+    );
+    if (config.stopOnEmpty !== false && (!data || Array.isArray(data) && data.length === 0)) {
+      break;
+    }
+    yield data;
+    page++;
+  }
+}
+
+// src/Helper/Batch.ts
+async function batch(tasks, options = {}) {
+  const concurrency = options.concurrency ?? tasks.length;
+  const failFast = options.failFast ?? false;
+  const results = [];
+  const errors = [];
+  let index = 0;
+  async function worker() {
+    while (index < tasks.length) {
+      const i = index++;
+      try {
+        results[i] = await tasks[i]();
+      } catch (err) {
+        errors[i] = err;
+        if (failFast) throw err;
+      }
+    }
+  }
+  await Promise.all(
+    Array.from({ length: concurrency }, worker)
+  );
+  return { results, errors };
+}
+
+// src/index.ts
+var windClient = class {
+  constructor(baseURL = "") {
+    this.baseURL = baseURL;
+    this.breaker = new CircuitBreaker();
+  }
+  async request(path, options = {}) {
+    if (!this.breaker.canRequest()) {
+      throw new Error("Circuit breaker is open");
+    }
+    const exec = async () => {
+      return coreRequest(this.baseURL + path, options);
+    };
+    try {
+      const result = options.retry ? await withRetry(exec, options.retry) : await exec();
+      this.breaker.success();
+      return result;
+    } catch (err) {
+      if (this.shouldTripBreaker(err)) {
+        this.breaker.failure();
+      }
+      throw err;
+    }
+  }
+  get(path, options) {
+    return this.request(path, { ...options, method: "GET" });
+  }
+  post(path, body, options) {
+    return this.request(path, { ...options, method: "POST", body });
+  }
+  paginate(path, config) {
+    return paginate(this.get.bind(this), path, config);
+  }
+  batch(tasks, options) {
+    return batch(tasks, options);
+  }
+  shouldTripBreaker(err) {
+    const status = err?.status;
+    if (!status) return true;
+    if (status >= 500) return true;
+    if (status === 429) return true;
+    return false;
+  }
+};
+function wind(config = {}) {
+  return new windClient(config.baseURL ?? "");
+}
+var defaultWind = new windClient();
+var index_default = defaultWind;
+export {
+  index_default as default,
+  wind,
+  windClient
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@winxs/wind",
+  "version": "0.1.0",
+  "description": "Modern HTTP orchestration client for pagination, retries, batching, and failure-safe APIs",
+  "license": "MIT",
+  "author": "Winxs",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "http",
+    "fetch",
+    "axios",
+    "client",
+    "pagination",
+    "retry",
+    "batch",
+    "workers"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/winxs/wind"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}