rust-fetch 1.0.0 → 1.0.1

package/README.md

@@ -1,192 +1,288 @@
-# Rust Fetch - World-Class HTTP Client for WebAssembly
+# rust-fetch
 
-[![License: MIT/Apache-2.0](https://img.shields.io/badge/License-MIT%2FApache--2.0-blue.svg)](LICENSE)
-[![Rust](https://img.shields.io/badge/rust-%23000000.svg?style=flat&logo=rust&logoColor=white)](https://www.rust-lang.org/)
-[![WebAssembly](https://img.shields.io/badge/WebAssembly-654FF0?style=flat&logo=WebAssembly&logoColor=white)](https://webassembly.org/)
+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.
 
-A production-ready, world-class HTTP client library for WebAssembly with excellent error handling, retry logic, and a clean API design.
+## Features
 
-## 🚀 Features
+- 🚀 **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
 
-- **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
 
-## 📦 Installation
+```bash
+npm install rust-fetch
+```
 
-Add this to your `Cargo.toml`:
+or
 
-```toml
-[dependencies]
-rust-fetch = "1.0.0"
+```bash
+yarn add rust-fetch
 ```
 
-For WebAssembly projects, make sure to include:
+## Project Structure
 
-```toml
-[dependencies]
-wasm-bindgen = "0.2"
-wasm-bindgen-futures = "0.4"
+```
+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
 ```
 
-## 🔧 Usage
+## Usage
 
-### Simple API
+### Client-Side (Browser)
 
-For quick and easy HTTP requests:
+```typescript
+import initWasm, { 
+  fetch_wasm_json, 
+  fetch_wasm_html, 
+  greet, 
+  add 
+} from 'rust-fetch/client';
 
-```rust
-use rust_fetch::prelude::*;
+// Initialize WASM module
+await initWasm();
 
 // Fetch JSON data
-let data = fetch_json("https://api.example.com/data").await?;
-
-// Fetch text/HTML
-let html = fetch_text("https://example.com").await?;
-
-// Advanced request with options
-let response = fetch_with_options(
-    "https://api.example.com/users",
-    "POST",
-    headers_obj, // JavaScript headers object
-    Some(r#"{"name": "John Doe"}"#.to_string()),
-).await?;
-```
-
-### Advanced Client API
-
-For more control and configuration:
-
-```rust
-use rust_fetch::client::Client;
-use rust_fetch::types::RetryConfig;
-use std::time::Duration;
-
-// Create a configured client
-let client = Client::builder()
-    .base_url("https://api.example.com")
-    .default_header("Authorization", "Bearer token")
-    .timeout(Duration::from_secs(10))
-    .retry_config(RetryConfig {
-        max_retries: 3,
-        initial_delay: Duration::from_millis(100),
-        ..Default::default()
-    })
-    .build()?;
-
-// Make requests
-let response = client
-    .post("/users")
-    .json(&serde_json::json!({
-        "name": "Jane Doe",
-        "email": "jane@example.com"
-    }))?
-    .send()
-    .await?;
-
-// Access response data
-println!("Status: {}", response.status);
-if let Some(json) = response.json() {
-    println!("Response: {:?}", json);
+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);
 }
+
+// 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);
+}
+
+// Use utility functions
+const greeting = greet('World');
+console.log(greeting); // "Hello, World!"
+
+const sum = add(5, 3);
+console.log(sum); // 8
 ```
 
-### WebAssembly JavaScript API
+### Server-Side (Node.js)
 
-When compiled to WebAssembly, the library exposes a JavaScript-friendly API:
+```typescript
+import initWasm, { 
+  fetch_wasm_json, 
+  fetch_wasm_html,
+  greet,
+  add 
+} from 'rust-fetch/server';
 
-```javascript
-import init, { WasmClient, fetch_json, fetch_text } from './rust_fetch.js';
+// WASM is automatically initialized on import
 
-await init();
+// 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);
+}
+
+// Use other functions similarly
+```
 
-// Simple API
-const data = await fetch_json("https://api.example.com/data");
-const html = await fetch_text("https://example.com");
+## API Reference
 
-// Client API
-const client = new WasmClient();
-const response = await client.get("https://api.example.com/users");
-console.log(response);
+### HTTP Functions
+
+#### `fetch_wasm_json(url: string): Promise<any>`
+Fetches JSON data from the specified URL and returns it as a JavaScript object.
+
+```typescript
+const data = await fetch_wasm_json('https://jsonplaceholder.typicode.com/todos/1');
 ```
 
-## 🏗️ Architecture
+#### `fetch_wasm_json_new(url: string): Promise<any>`
+Alternative implementation that returns a Promise directly (useful for different async patterns).
 
-The library is organized into several modules:
+```typescript
+const promise = fetch_wasm_json_new('https://api.example.com/data');
+const data = await promise;
+```
 
-- **`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
+#### `fetch_wasm_map(url: string): Promise<any>`
+Fetches JSON data and returns it as a JavaScript object using `serde_wasm_bindgen`.
 
-### Error Handling
+```typescript
+const data = await fetch_wasm_map('https://api.example.com/data');
+```
+
+#### `fetch_wasm_html(url: string): Promise<string>`
+Fetches HTML content from the specified URL and returns it as a string.
 
-The library provides rich error types that preserve context:
+```typescript
+const html = await fetch_wasm_html('https://example.com');
+```
 
-```rust
-use rust_fetch::error::{Error, Result};
+#### `fetch_wasm_api(): Promise<any>`
+Fetches data from a predefined API endpoint (JSONPlaceholder todo item).
 
-match fetch_json(url).await {
-    Ok(data) => println!("Success: {:?}", data),
-    Err(Error::Network { message, source }) => {
-        eprintln!("Network error: {}", message);
-    }
-    Err(Error::Http { status, status_text, body }) => {
-        eprintln!("HTTP {}: {}", status, status_text);
-    }
-    Err(e) => eprintln!("Other error: {}", e),
-}
+```typescript
+const todo = await fetch_wasm_api();
 ```
 
-### Request Building
+### Utility Functions
+
+#### `greet(name: string): string`
+Returns a greeting message.
+
+```typescript
+const message = greet('Alice'); // "Hello, Alice!"
+```
 
-The client provides a fluent API for building requests:
+#### `add(a: number, b: number): number`
+Adds two numbers together.
 
-```rust
-let response = client
-    .request(Method::Put, "/users/123")
-    .header("Content-Type", "application/json")
-    .header("X-Custom-Header", "value")
-    .timeout(Duration::from_secs(5))
-    .json(&updated_user)?
-    .send()
-    .await?;
+```typescript
+const result = add(10, 20); // 30
 ```
 
-## 🧪 Testing
+## Building from Source
 
-Run tests for native target:
+### Prerequisites
 
+- Rust (latest stable version)
+- Node.js (v14 or higher)
+- wasm-pack (`cargo install wasm-pack`)
+
+### Build Steps
+
+1. Clone the repository:
 ```bash
-cargo test
+git clone https://github.com/yourusername/rust-fetch.git
+cd rust-fetch
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Build the WASM module:
+```bash
+npm run build:wasm
+```
+
+4. Build TypeScript files:
+```bash
+npm run build
 ```
 
-Run tests for WebAssembly target:
+## Development
+
+### Building the WASM Module
 
 ```bash
-wasm-pack test --headless --chrome
+cd wasm-module
+wasm-pack build --target web
 ```
 
-## 🤝 Contributing
+This generates the `pkg` directory with JavaScript bindings and TypeScript definitions.
+
+### Running Tests
+
+For Rust tests:
+```bash
+cd wasm-module
+cargo test
+
+cd ../rust-fetch-package
+cargo test
+```
+
+## Performance Considerations
+
+- The WASM module adds a small overhead for initialization (~100-200ms on first load)
+- Once loaded, HTTP operations benefit from Rust's efficient memory management
+- Best suited for applications that make multiple HTTP requests or need predictable performance
+
+## Browser Support
+
+- Chrome 57+
+- Firefox 52+
+- Safari 11+
+- Edge 16+
+- Node.js 14+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the ISC License - see the LICENSE file for details.
+
+## Troubleshooting
+
+### WASM Module Not Loading
+
+If you encounter issues with the WASM module not loading:
+
+1. Ensure your server supports the `application/wasm` MIME type
+2. Check that the WASM file is being served correctly
+3. Verify you're awaiting the `initWasm()` call before using any functions
+
+### CORS Issues
+
+When fetching from external APIs, ensure:
+
+1. The target server allows CORS requests
+2. You're using HTTPS URLs in production
+3. Consider using a proxy server for APIs that don't support CORS
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+### Node.js Path Issues
 
-## 📄 License
+If you encounter path resolution issues in Node.js:
 
-This project is licensed under either of
+1. Ensure the package is installed correctly
+2. Check that the WASM file exists in `node_modules/rust-fetch/wasm-module/pkg/`
+3. Try reinstalling the package
 
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+## Acknowledgments
 
-at your option.
+- Built with [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen)
+- Uses [reqwest](https://github.com/seanmonstar/reqwest) for HTTP operations
+- Inspired by the Rust and WebAssembly community
 
-## 🙏 Acknowledgments
+## Roadmap
 
-Built with love using:
-- [reqwest](https://github.com/seanmonstar/reqwest) - HTTP client
-- [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen) - WebAssembly bindings
-- [serde](https://github.com/serde-rs/serde) - Serialization framework
+- [ ] Add support for POST, PUT, DELETE methods
+- [ ] Implement request headers customization
+- [ ] Add streaming support for large responses
+- [ ] Implement request cancellation
+- [ ] Add comprehensive test suite
+- [ ] Performance benchmarks against native fetch
+- [ ] Support for form data and file uploads
+- [ ] WebSocket support
+- [ ] Request/response interceptors

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.0",
+  "version": "1.0.1",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",
@@ -28,4 +28,4 @@
     "fetch",
     "webassembly"
   ]
-}
+}