rust-fetch 1.0.1 → 1.0.2

package/README.md

@@ -1,16 +1,22 @@
 # rust-fetch
 
-A WebAssembly-powered HTTP client library for JavaScript/TypeScript applications, built with Rust. This library provides fast, memory-safe HTTP operations through WebAssembly bindings, allowing you to leverage Rust's performance and safety guarantees in your web applications.
+[![npm version](https://img.shields.io/npm/v/rust-fetch.svg)](https://www.npmjs.com/package/rust-fetch)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+[![WebAssembly](https://img.shields.io/badge/WebAssembly-654FF0?style=flat&logo=WebAssembly&logoColor=white)](https://webassembly.org/)
 
-## Features
+A high-performance, world-class HTTP client for JavaScript/TypeScript powered by WebAssembly. Built with Rust for blazing-fast, memory-safe HTTP operations in both browser and Node.js environments.
 
-- 🚀 **High Performance**: Leverage Rust's performance for HTTP operations through WebAssembly
-- 🔐 **Memory Safe**: Built with Rust's memory safety guarantees
-- 🌐 **Cross-Platform**: Works in both browser and Node.js environments
-- 📦 **TypeScript Support**: Full TypeScript definitions included
-- 🛠️ **Multiple Utilities**: HTTP fetching, JSON parsing, HTML retrieval, and utility functions
+## 🚀 Features
 
-## Installation
+- **Type-safe HTTP Client**: Builder pattern for constructing requests with compile-time safety
+- **Comprehensive Error Handling**: Detailed error types with context and proper error chaining
+- **Automatic Retries**: Built-in retry logic with exponential backoff for transient failures
+- **Multiple Response Formats**: Support for JSON, text, and binary responses
+- **Platform Optimized**: Specific optimizations for both WASM and native targets
+- **Developer Friendly**: Clean API with both simple functions and advanced client builders
+- **Backward Compatible**: Maintains compatibility with legacy API while providing modern alternatives
+
+## 📦 Installation
 
 ```bash
 npm install rust-fetch
@@ -22,199 +28,172 @@ or
 yarn add rust-fetch
 ```
 
-## Project Structure
+## 🔧 Usage
 
-```
-rust-fetch/
-├── rust-fetch-package/    # Main Rust package (currently basic implementation)
-│   ├── Cargo.toml
-│   └── src/
-│       └── lib.rs
-├── wasm-module/          # WebAssembly module with HTTP and utility functions
-│   ├── Cargo.toml
-│   ├── pkg/              # Generated WASM package
-│   └── src/
-│       ├── greetings/    # Greeting utilities
-│       ├── http/         # HTTP client functions
-│       ├── math/         # Math utilities
-│       └── lib.rs
-├── client.ts             # Client-side entry point
-├── server.ts             # Server-side entry point
-├── package.json          # NPM package configuration
-└── tsconfig.json         # TypeScript configuration
-```
+### Simple API
 
-## Usage
+For quick and easy HTTP requests:
 
-### Client-Side (Browser)
+### WASM Client Example
+How to use the imported `WasmClient` to make HTTP requests from the browser or Node.js environment:
 
-```typescript
-import initWasm, { 
-  fetch_wasm_json, 
-  fetch_wasm_html, 
-  greet, 
-  add 
-} from 'rust-fetch/client';
+#### Simple GET Request
+Here's how to make a simple GET request using `WasmClient`:
 
-// Initialize WASM module
-await initWasm();
+```javascript
+import init, { WasmClient } from 'rust-fetch/client';
 
-// Fetch JSON data
-try {
-  const data = await fetch_wasm_json('https://api.example.com/data');
-  console.log('JSON data:', data);
-} catch (error) {
-  console.error('Error fetching JSON:', error);
-}
+await init();
 
-// Fetch HTML content
-try {
-  const html = await fetch_wasm_html('https://example.com');
-  console.log('HTML content:', html);
-} catch (error) {
-  console.error('Error fetching HTML:', error);
-}
+const client = new WasmClient();
+
+client.get('https://jsonplaceholder.typicode.com/posts/1')
+    .then(response => console.log(response))
+    .catch(error => console.error('Error:', error));
+```
+
+#### POST Request with JSON
+Here's how to make a POST request with a JSON body:
 
-// Use utility functions
-const greeting = greet('World');
-console.log(greeting); // "Hello, World!"
+```javascript
+const data = { title: 'foo', body: 'bar', userId: 1 };
 
-const sum = add(5, 3);
-console.log(sum); // 8
+client.post_json('https://jsonplaceholder.typicode.com/posts', data)
+    .then(response => console.log(response))
+    .catch(error => console.error('Error:', error));
 ```
 
-### Server-Side (Node.js)
+### Using Fetch Functions
 
-```typescript
-import initWasm, { 
-  fetch_wasm_json, 
-  fetch_wasm_html,
-  greet,
-  add 
-} from 'rust-fetch/server';
+```javascript
+import init, { fetch_json, fetch_text } from 'rust-fetch/client';
 
-// WASM is automatically initialized on import
+// Initialize WASM module
+await init();
 
 // Fetch JSON data
 try {
-  const data = await fetch_wasm_json('https://api.example.com/data');
+  const data = await fetch_json('https://api.example.com/data');
   console.log('JSON data:', data);
 } catch (error) {
   console.error('Error fetching JSON:', error);
 }
 
-// Use other functions similarly
+// Fetch text/HTML
+try {
+  const html = await fetch_text('https://example.com');
+  console.log('HTML content:', html);
+} catch (error) {
+  console.error('Error fetching HTML:', error);
+}
 ```
 
-## API Reference
+### Advanced Client API
 
-### HTTP Functions
+For more control and enhanced configurations, use the `fetch_with_options` to fine-tune HTTP requests:
 
-#### `fetch_wasm_json(url: string): Promise<any>`
-Fetches JSON data from the specified URL and returns it as a JavaScript object.
+#### Using Advanced Options
+You can specify HTTP method, headers, and body:
 
-```typescript
-const data = await fetch_wasm_json('https://jsonplaceholder.typicode.com/todos/1');
-```
+```javascript
+import { fetch_with_options } from 'rust-fetch/client';
 
-#### `fetch_wasm_json_new(url: string): Promise<any>`
-Alternative implementation that returns a Promise directly (useful for different async patterns).
+const url = 'https://jsonplaceholder.typicode.com/posts';
+const method = 'POST';
+const headers = { 'Content-Type': 'application/json' };
+const body = JSON.stringify({ userId: 1, title: 'foo', body: 'bar' });
 
-```typescript
-const promise = fetch_wasm_json_new('https://api.example.com/data');
-const data = await promise;
+fetch_with_options(url, method, headers, body)
+    .then(response => console.log(response))
+    .catch(error => console.error('Error:', error));
 ```
 
-#### `fetch_wasm_map(url: string): Promise<any>`
-Fetches JSON data and returns it as a JavaScript object using `serde_wasm_bindgen`.
+## 🏗️ Architecture
 
-```typescript
-const data = await fetch_wasm_map('https://api.example.com/data');
-```
+The library is organized into several modules:
 
-#### `fetch_wasm_html(url: string): Promise<string>`
-Fetches HTML content from the specified URL and returns it as a string.
+- **`error`**: Comprehensive error types with detailed context
+- **`types`**: Core types like `Method`, `Headers`, `Response`, etc.
+- **`client`**: The main HTTP client with builder pattern
+- **`http`**: High-level convenience functions for common use cases
 
-```typescript
-const html = await fetch_wasm_html('https://example.com');
-```
+### Error Handling
 
-#### `fetch_wasm_api(): Promise<any>`
-Fetches data from a predefined API endpoint (JSONPlaceholder todo item).
+The library provides rich error types that preserve context:
 
-```typescript
-const todo = await fetch_wasm_api();
+```javascript
+try {
+  const data = await fetch_json(url);
+  console.log('Success:', data);
+} catch (error) {
+  // Error handling with detailed context
+  console.error('Failed to fetch:', error.message);
+}
 ```
 
-### Utility Functions
+## API Reference
 
-#### `greet(name: string): string`
-Returns a greeting message.
+### HTTP Functions
 
-```typescript
-const message = greet('Alice'); // "Hello, Alice!"
-```
+#### `fetch_json(url: string): Promise<any>`
+Fetches JSON data from the specified URL and returns it as a JavaScript object.
 
-#### `add(a: number, b: number): number`
-Adds two numbers together.
+```javascript
+import { fetch_json } from 'rust-fetch/client';
 
-```typescript
-const result = add(10, 20); // 30
+const data = await fetch_json('https://jsonplaceholder.typicode.com/todos/1');
 ```
 
-## Building from Source
+#### `fetch_text(url: string): Promise<string>`
+Fetches text/HTML content from the specified URL and returns it as a string.
 
-### Prerequisites
+```javascript
+import { fetch_text } from 'rust-fetch/client';
 
-- Rust (latest stable version)
-- Node.js (v14 or higher)
-- wasm-pack (`cargo install wasm-pack`)
-
-### Build Steps
-
-1. Clone the repository:
-```bash
-git clone https://github.com/yourusername/rust-fetch.git
-cd rust-fetch
+const html = await fetch_text('https://example.com');
 ```
 
-2. Install dependencies:
-```bash
-npm install
-```
+#### `fetch_with_options(url: string, method: string, headers: object, body?: string): Promise<object>`
+Advanced fetch function with full control over the request.
 
-3. Build the WASM module:
-```bash
-npm run build:wasm
-```
+```javascript
+import { fetch_with_options } from 'rust-fetch/client';
 
-4. Build TypeScript files:
-```bash
-npm run build
+const response = await fetch_with_options(
+    'https://api.example.com/users',
+    'POST',
+    { 'Content-Type': 'application/json' },
+    JSON.stringify({ name: 'John Doe' })
+);
 ```
 
-## Development
+### WasmClient Class
 
-### Building the WASM Module
+#### `new WasmClient()`
+Creates a new HTTP client instance.
 
-```bash
-cd wasm-module
-wasm-pack build --target web
+```javascript
+const client = new WasmClient();
 ```
 
-This generates the `pkg` directory with JavaScript bindings and TypeScript definitions.
+#### `client.get(url: string): Promise<object>`
+Performs a GET request.
 
-### Running Tests
+```javascript
+const response = await client.get('https://api.example.com/data');
+```
 
-For Rust tests:
-```bash
-cd wasm-module
-cargo test
+#### `client.post_json(url: string, body: object): Promise<object>`
+Performs a POST request with JSON body.
 
-cd ../rust-fetch-package
-cargo test
+```javascript
+const response = await client.post_json('https://api.example.com/users', {
+    name: 'Jane Doe',
+    email: 'jane@example.com'
+});
 ```
 
+
 ## Performance Considerations
 
 - The WASM module adds a small overhead for initialization (~100-200ms on first load)

package/package.json

@@ -5,7 +5,7 @@
     "Asem Qaffaf <asem@qaffaf.com>"
   ],
   "description": "A world-class WebAssembly HTTP client library with excellent error handling and clean API",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",