zipfetch 1.0.0

package/README.md

@@ -0,0 +1,328 @@
+# zipfetch
+
+> Ultra-fast, lightweight HTTP client built on native fetch - retries, interceptors, caching, rate limiting
+
+[![npm version](https://img.shields.io/npm/v/zipfetch.svg)](https://www.npmjs.com/package/zipfetch)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why zipfetch?
+
+- **Tiny**: ~5KB minified (vs Axios 29KB, Got 48KB)
+- **Zero dependencies**: Built on native `fetch` (Node 18+)
+- **Modern**: ESM, TypeScript, async/await
+- **Powerful**: Retries, interceptors, caching, rate limiting
+- **Familiar API**: Similar to Axios, easy to migrate
+
+## Installation
+
+```bash
+npm install zipfetch
+```
+
+## Quick Start
+
+```typescript
+import zipfetch from 'zipfetch';
+
+// Simple GET request
+const { data } = await zipfetch.get('https://api.example.com/users');
+
+// POST with data
+const { data: user } = await zipfetch.post('https://api.example.com/users', {
+  name: 'John',
+  email: 'john@example.com'
+});
+
+// With query params
+const { data: results } = await zipfetch.get('https://api.example.com/search', {
+  params: { q: 'typescript', page: 1 }
+});
+```
+
+## Comparison with Alternatives
+
+| Feature | zipfetch | Axios | Got | node-fetch |
+|---------|----------|-------|-----|------------|
+| Size (gzip) | **~5KB** | 29KB | 48KB | 8KB |
+| Dependencies | **0** | 8 | 11 | 0 |
+| Native fetch | **Yes** | No | No | Polyfill |
+| Retries | **Built-in** | No | Yes | No |
+| Interceptors | **Yes** | Yes | Hooks | No |
+| Caching | **Built-in** | No | Plugin | No |
+| Rate Limiting | **Built-in** | No | Plugin | No |
+| TypeScript | **Yes** | Yes | Yes | @types |
+| Node 18+ | **Yes** | Yes | Yes | Yes |
+| Browser | **Yes** | Yes | No | No |
+
+## API Reference
+
+### Creating an Instance
+
+```typescript
+import { create } from 'zipfetch';
+
+const api = create({
+  baseURL: 'https://api.example.com',
+  timeout: 10000,
+  headers: {
+    'Authorization': 'Bearer token'
+  }
+});
+
+const { data } = await api.get('/users');
+```
+
+### Request Methods
+
+```typescript
+zipfetch.get(url, config?)
+zipfetch.post(url, data?, config?)
+zipfetch.put(url, data?, config?)
+zipfetch.patch(url, data?, config?)
+zipfetch.delete(url, config?)
+zipfetch.head(url, config?)
+zipfetch.options(url, config?)
+```
+
+### Request Config
+
+```typescript
+interface RequestConfig {
+  url?: string;
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+  baseURL?: string;
+  headers?: Record<string, string>;
+  params?: Record<string, string | number | boolean>;
+  data?: unknown;
+  timeout?: number;
+  retry?: {
+    attempts?: number;
+    delay?: number;
+    backoff?: 'linear' | 'exponential';
+    retryOn?: number[];
+  };
+  cache?: boolean;
+}
+```
+
+### Response Object
+
+```typescript
+interface ZipResponse<T> {
+  data: T;
+  status: number;
+  statusText: string;
+  headers: Headers;
+  config: RequestConfig;
+}
+```
+
+## Features
+
+### Automatic Retries
+
+```typescript
+import { create } from 'zipfetch';
+
+const api = create({
+  retry: {
+    attempts: 3,              // Retry up to 3 times
+    delay: 1000,              // Start with 1 second delay
+    backoff: 'exponential',   // 1s, 2s, 4s
+    retryOn: [500, 502, 503]  // Retry on these status codes
+  }
+});
+
+// Will automatically retry on failure
+const { data } = await api.get('/flaky-endpoint');
+```
+
+### Interceptors
+
+```typescript
+import zipfetch from 'zipfetch';
+
+// Request interceptor
+zipfetch.interceptors.request.use((config) => {
+  config.headers = {
+    ...config.headers,
+    'X-Request-ID': crypto.randomUUID()
+  };
+  return config;
+});
+
+// Response interceptor
+zipfetch.interceptors.response.use((response) => {
+  console.log(`Response: ${response.status}`);
+  return response;
+});
+
+// Error interceptor
+zipfetch.interceptors.error.use((error) => {
+  if (error.status === 401) {
+    // Handle unauthorized
+    window.location.href = '/login';
+  }
+  return error;
+});
+```
+
+### Response Caching
+
+```typescript
+import { create } from 'zipfetch';
+
+const api = create({
+  cache: {
+    enabled: true,
+    ttl: 60000,           // Cache for 60 seconds
+    methods: ['GET']      // Only cache GET requests
+  }
+});
+
+// First request hits the network
+await api.get('/users');
+
+// Second request returns cached response
+await api.get('/users');
+
+// Clear cache manually
+api.clearCache();
+```
+
+### Rate Limiting
+
+```typescript
+import { create } from 'zipfetch';
+
+const api = create({
+  rateLimit: {
+    requests: 10,       // Max 10 requests
+    interval: 1000      // Per second
+  }
+});
+
+// Requests will automatically queue if rate limit is exceeded
+for (let i = 0; i < 20; i++) {
+  api.get('/endpoint'); // Will spread across 2 seconds
+}
+```
+
+### Timeout
+
+```typescript
+import zipfetch from 'zipfetch';
+
+try {
+  await zipfetch.get('/slow-endpoint', {
+    timeout: 5000  // 5 second timeout
+  });
+} catch (error) {
+  if (error.code === 'TIMEOUT') {
+    console.log('Request timed out');
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+import zipfetch, { ZipError } from 'zipfetch';
+
+try {
+  await zipfetch.get('/not-found');
+} catch (error) {
+  if (error instanceof ZipError) {
+    console.log(error.status);      // 404
+    console.log(error.response);    // Full response object
+    console.log(error.config);      // Request config
+    console.log(error.code);        // 'TIMEOUT' | 'NETWORK' | 'ABORT' | undefined
+  }
+}
+```
+
+### FormData & File Uploads
+
+```typescript
+import zipfetch from 'zipfetch';
+
+const formData = new FormData();
+formData.append('file', fileInput.files[0]);
+formData.append('name', 'My File');
+
+const { data } = await zipfetch.post('/upload', formData);
+// Content-Type is automatically set to multipart/form-data
+```
+
+## Migration from Axios
+
+```typescript
+// Axios
+import axios from 'axios';
+const api = axios.create({ baseURL: 'https://api.example.com' });
+const { data } = await api.get('/users');
+
+// zipfetch
+import { create } from 'zipfetch';
+const api = create({ baseURL: 'https://api.example.com' });
+const { data } = await api.get('/users');
+```
+
+## Migration from node-fetch
+
+```typescript
+// node-fetch
+import fetch from 'node-fetch';
+const response = await fetch('https://api.example.com/users');
+const data = await response.json();
+
+// zipfetch
+import zipfetch from 'zipfetch';
+const { data } = await zipfetch.get('https://api.example.com/users');
+```
+
+## TypeScript
+
+Full TypeScript support with generics:
+
+```typescript
+import zipfetch from 'zipfetch';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+// Type-safe response
+const { data } = await zipfetch.get<User[]>('/users');
+data.forEach(user => console.log(user.name));
+
+// Type-safe post
+const { data: newUser } = await zipfetch.post<User>('/users', {
+  name: 'John',
+  email: 'john@example.com'
+});
+```
+
+## Browser Support
+
+Works in all modern browsers that support native `fetch`:
+- Chrome 42+
+- Firefox 39+
+- Safari 10.1+
+- Edge 14+
+
+For older browsers, use a fetch polyfill.
+
+## Node.js Support
+
+Requires Node.js 18+ (native fetch support).
+
+## License
+
+MIT
+
+---
+
+**Made for speed and simplicity**

package/dist/cache.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Response caching implementation
+ */
+import type { RequestConfig, ZipResponse } from './types.js';
+export declare class ResponseCache {
+    private cache;
+    private generateKey;
+    get<T>(url: string, config: RequestConfig): ZipResponse<T> | null;
+    set<T>(url: string, config: RequestConfig, response: ZipResponse<T>, ttl: number): void;
+    clear(): void;
+    delete(url: string, config: RequestConfig): boolean;
+    size(): number;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAQ7D,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAA0C;IAEvD,OAAO,CAAC,WAAW;IAMnB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI;IAcjE,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IASvF,KAAK,IAAI,IAAI;IAIb,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO;IAKnD,IAAI,IAAI,MAAM;CAGf"}

package/dist/cache.js

@@ -0,0 +1,41 @@
+/**
+ * Response caching implementation
+ */
+export class ResponseCache {
+    cache = new Map();
+    generateKey(url, config) {
+        const params = config.params ? JSON.stringify(config.params) : '';
+        const headers = config.headers ? JSON.stringify(config.headers) : '';
+        return `${config.method || 'GET'}:${url}:${params}:${headers}`;
+    }
+    get(url, config) {
+        const key = this.generateKey(url, config);
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        if (Date.now() - entry.timestamp > entry.ttl) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.data;
+    }
+    set(url, config, response, ttl) {
+        const key = this.generateKey(url, config);
+        this.cache.set(key, {
+            data: response,
+            timestamp: Date.now(),
+            ttl,
+        });
+    }
+    clear() {
+        this.cache.clear();
+    }
+    delete(url, config) {
+        const key = this.generateKey(url, config);
+        return this.cache.delete(key);
+    }
+    size() {
+        return this.cache.size;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,MAAM,OAAO,aAAa;IAChB,KAAK,GAAG,IAAI,GAAG,EAA+B,CAAC;IAE/C,WAAW,CAAC,GAAW,EAAE,MAAqB;QACpD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,OAAO,GAAG,MAAM,CAAC,MAAM,IAAI,KAAK,IAAI,GAAG,IAAI,MAAM,IAAI,OAAO,EAAE,CAAC;IACjE,CAAC;IAED,GAAG,CAAI,GAAW,EAAE,MAAqB;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAA8B,CAAC;QAE/D,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QAExB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;YAC7C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC,IAAsB,CAAC;IACtC,CAAC;IAED,GAAG,CAAI,GAAW,EAAE,MAAqB,EAAE,QAAwB,EAAE,GAAW;QAC9E,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,GAAG;SACJ,CAAC,CAAC;IACL,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,MAAM,CAAC,GAAW,EAAE,MAAqB;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF"}

package/dist/client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Main ZipFetch client class
+ */
+import type { ZipFetchConfig, RequestConfig, ZipResponse, RequestInterceptor, ResponseInterceptor, ErrorInterceptor } from './types.js';
+export declare class ZipFetch {
+    private config;
+    private cache;
+    private rateLimiter?;
+    private requestInterceptors;
+    private responseInterceptors;
+    private errorInterceptors;
+    constructor(config?: ZipFetchConfig);
+    interceptors: {
+        request: {
+            use: (interceptor: RequestInterceptor) => number;
+            eject: (index: number) => void;
+            clear: () => void;
+        };
+        response: {
+            use: (interceptor: ResponseInterceptor) => number;
+            eject: (index: number) => void;
+            clear: () => void;
+        };
+        error: {
+            use: (interceptor: ErrorInterceptor) => number;
+            eject: (index: number) => void;
+            clear: () => void;
+        };
+    };
+    request<T = unknown>(config: RequestConfig): Promise<ZipResponse<T>>;
+    private buildUrl;
+    private isCacheEnabled;
+    private executeWithRetry;
+    private executeRequest;
+    private prepareBody;
+    private parseResponse;
+    private shouldRetry;
+    private delay;
+    get<T = unknown>(url: string, config?: Omit<RequestConfig, 'url' | 'method'>): Promise<ZipResponse<T>>;
+    post<T = unknown>(url: string, data?: unknown, config?: Omit<RequestConfig, 'url' | 'method' | 'data'>): Promise<ZipResponse<T>>;
+    put<T = unknown>(url: string, data?: unknown, config?: Omit<RequestConfig, 'url' | 'method' | 'data'>): Promise<ZipResponse<T>>;
+    patch<T = unknown>(url: string, data?: unknown, config?: Omit<RequestConfig, 'url' | 'method' | 'data'>): Promise<ZipResponse<T>>;
+    delete<T = unknown>(url: string, config?: Omit<RequestConfig, 'url' | 'method'>): Promise<ZipResponse<T>>;
+    head<T = unknown>(url: string, config?: Omit<RequestConfig, 'url' | 'method'>): Promise<ZipResponse<T>>;
+    options<T = unknown>(url: string, config?: Omit<RequestConfig, 'url' | 'method'>): Promise<ZipResponse<T>>;
+    clearCache(): void;
+    create(config: ZipFetchConfig): ZipFetch;
+    getConfig(): ZipFetchConfig;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,WAAW,EAGX,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAKpB,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,WAAW,CAAC,CAAc;IAElC,OAAO,CAAC,mBAAmB,CAA4B;IACvD,OAAO,CAAC,oBAAoB,CAA6B;IACzD,OAAO,CAAC,iBAAiB,CAA0B;gBAEvC,MAAM,GAAE,cAAmB;IAkBvC,YAAY;;+BAEW,kBAAkB;2BAItB,MAAM;;;;+BAQF,mBAAmB;2BAIvB,MAAM;;;;+BAQF,gBAAgB;2BAIpB,MAAM;;;MAOvB;IAMI,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAyC1E,OAAO,CAAC,QAAQ;IAyBhB,OAAO,CAAC,cAAc;YAQR,gBAAgB;YAoChB,cAAc;IAqE5B,OAAO,CAAC,WAAW;YAsBL,aAAa;IAc3B,OAAO,CAAC,WAAW;YAYL,KAAK;IAqBnB,GAAG,CAAC,CAAC,GAAG,OAAO,EACb,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,QAAQ,CAAC,GAC7C,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI1B,IAAI,CAAC,CAAC,GAAG,OAAO,EACd,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,GACtD,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI1B,GAAG,CAAC,CAAC,GAAG,OAAO,EACb,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,GACtD,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI1B,KAAK,CAAC,CAAC,GAAG,OAAO,EACf,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,GACtD,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI1B,MAAM,CAAC,CAAC,GAAG,OAAO,EAChB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,QAAQ,CAAC,GAC7C,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI1B,IAAI,CAAC,CAAC,GAAG,OAAO,EACd,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,QAAQ,CAAC,GAC7C,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI1B,OAAO,CAAC,CAAC,GAAG,OAAO,EACjB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,QAAQ,CAAC,GAC7C,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAQ1B,UAAU,IAAI,IAAI;IAIlB,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ;IAIxC,SAAS,IAAI,cAAc;CAG5B"}