rust-fetch 0.7.2 → 1.0.1

package/README.md

@@ -0,0 +1,288 @@
+# 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.
+
+## 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
+
+## Installation
+
+```bash
+npm install rust-fetch
+```
+
+or
+
+```bash
+yarn add rust-fetch
+```
+
+## Project Structure
+
+```
+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
+
+### Client-Side (Browser)
+
+```typescript
+import initWasm, { 
+  fetch_wasm_json, 
+  fetch_wasm_html, 
+  greet, 
+  add 
+} from 'rust-fetch/client';
+
+// Initialize WASM module
+await initWasm();
+
+// 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);
+}
+
+// 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
+```
+
+### Server-Side (Node.js)
+
+```typescript
+import initWasm, { 
+  fetch_wasm_json, 
+  fetch_wasm_html,
+  greet,
+  add 
+} from 'rust-fetch/server';
+
+// WASM is automatically initialized on import
+
+// 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
+```
+
+## API Reference
+
+### 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');
+```
+
+#### `fetch_wasm_json_new(url: string): Promise<any>`
+Alternative implementation that returns a Promise directly (useful for different async patterns).
+
+```typescript
+const promise = fetch_wasm_json_new('https://api.example.com/data');
+const data = await promise;
+```
+
+#### `fetch_wasm_map(url: string): Promise<any>`
+Fetches JSON data and returns it as a JavaScript object using `serde_wasm_bindgen`.
+
+```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.
+
+```typescript
+const html = await fetch_wasm_html('https://example.com');
+```
+
+#### `fetch_wasm_api(): Promise<any>`
+Fetches data from a predefined API endpoint (JSONPlaceholder todo item).
+
+```typescript
+const todo = await fetch_wasm_api();
+```
+
+### Utility Functions
+
+#### `greet(name: string): string`
+Returns a greeting message.
+
+```typescript
+const message = greet('Alice'); // "Hello, Alice!"
+```
+
+#### `add(a: number, b: number): number`
+Adds two numbers together.
+
+```typescript
+const result = add(10, 20); // 30
+```
+
+## Building from Source
+
+### Prerequisites
+
+- 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
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Build the WASM module:
+```bash
+npm run build:wasm
+```
+
+4. Build TypeScript files:
+```bash
+npm run build
+```
+
+## Development
+
+### Building the WASM Module
+
+```bash
+cd wasm-module
+wasm-pack build --target web
+```
+
+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
+
+### Node.js Path Issues
+
+If you encounter path resolution issues in Node.js:
+
+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
+
+## Acknowledgments
+
+- 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
+
+## Roadmap
+
+- [ ] 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

@@ -1,30 +1,31 @@
 {
   "name": "rust-fetch",
-  "version": "0.7.2",
-  "publishConfig": {
-    "access": "public"
+  "type": "module",
+  "collaborators": [
+    "Asem Qaffaf <asem@qaffaf.com>"
+  ],
+  "description": "A world-class WebAssembly HTTP client library with excellent error handling and clean API",
+  "version": "1.0.1",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/asemqaffaf/rust-fetch"
   },
-  "export": {
-    "fetch": "./wasm-module/pkg/wasm_module",
-    "server": "server.ts",
-    "client": "client.ts"
-  },
-  "scripts": {
-    "build": "cd wasm-module && tsc",
-    "build:wasm": "cd wasm-module && rm -rf pkg && wasm-pack build --target web && cd pkg && rm -rf .gitignore",
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "dependencies": {
-    "path": "^0.12.7",
-    "wasm-module": "file:wasm-module/pkg"
-  },
-  "devDependencies": {
-    "@types/node": "^22.13.5",
-    "typescript": "^5.7.3"
-  },
-  "main": "index.js",
-  "description": ""
+  "files": [
+    "rust_fetch_bg.wasm",
+    "rust_fetch.js",
+    "rust_fetch.d.ts"
+  ],
+  "main": "rust_fetch.js",
+  "types": "rust_fetch.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ],
+  "keywords": [
+    "wasm",
+    "http",
+    "client",
+    "fetch",
+    "webassembly"
+  ]
 }

package/rust_fetch.d.ts

@@ -0,0 +1,106 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Simple fetch function for JSON data
+ */
+export function fetch_json(url: string): Promise<any>;
+/**
+ * Fetch JSON data and return as a Promise
+ */
+export function fetch_json_promise(url: string): Promise<any>;
+/**
+ * Simple fetch function for text/HTML data
+ */
+export function fetch_text(url: string): Promise<string>;
+/**
+ * Advanced fetch function with full options
+ */
+export function fetch_with_options(url: string, method: string, headers: any, body?: string): Promise<any>;
+/**
+ * Create a configured HTTP client (exported for advanced use)
+ */
+export function create_client(): WasmClient;
+/**
+ * Fetch JSON data (deprecated, use fetch_json instead)
+ */
+export function fetch_wasm_json(url: string): Promise<any>;
+/**
+ * Fetch HTML data (deprecated, use fetch_text instead)
+ */
+export function fetch_wasm_html(url: string): Promise<string>;
+/**
+ * Fetch data and return as map (deprecated, use fetch_json instead)
+ */
+export function fetch_wasm_map(url: string): Promise<any>;
+/**
+ * Fetch API data (deprecated, use fetch_json instead)
+ */
+export function fetch_wasm_api(url: string): Promise<any>;
+/**
+ * WASM bindings for the client
+ */
+export class WasmClient {
+  free(): void;
+  /**
+   * Create a new client
+   */
+  constructor();
+  /**
+   * Make a GET request
+   */
+  get(url: string): Promise<any>;
+  /**
+   * Make a POST request with JSON body
+   */
+  post_json(url: string, body: any): Promise<any>;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly fetch_json: (a: number, b: number) => any;
+  readonly fetch_json_promise: (a: number, b: number) => any;
+  readonly fetch_text: (a: number, b: number) => any;
+  readonly fetch_with_options: (a: number, b: number, c: number, d: number, e: any, f: number, g: number) => any;
+  readonly create_client: () => [number, number, number];
+  readonly fetch_wasm_json: (a: number, b: number) => any;
+  readonly fetch_wasm_html: (a: number, b: number) => any;
+  readonly fetch_wasm_map: (a: number, b: number) => any;
+  readonly fetch_wasm_api: (a: number, b: number) => any;
+  readonly __wbg_wasmclient_free: (a: number, b: number) => void;
+  readonly wasmclient_new: () => [number, number, number];
+  readonly wasmclient_get: (a: number, b: number, c: number) => any;
+  readonly wasmclient_post_json: (a: number, b: number, c: number, d: any) => any;
+  readonly __wbindgen_malloc: (a: number, b: number) => number;
+  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+  readonly __wbindgen_exn_store: (a: number) => void;
+  readonly __externref_table_alloc: () => number;
+  readonly __wbindgen_export_4: WebAssembly.Table;
+  readonly __wbindgen_export_5: WebAssembly.Table;
+  readonly __externref_table_dealloc: (a: number) => void;
+  readonly closure243_externref_shim: (a: number, b: number, c: any) => void;
+  readonly closure265_externref_shim: (a: number, b: number, c: any, d: any) => void;
+  readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+/**
+* Instantiates the given `module`, which can either be bytes or
+* a precompiled `WebAssembly.Module`.
+*
+* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+*
+* @returns {InitOutput}
+*/
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+* for everything else, calls `WebAssembly.instantiate` directly.
+*
+* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+*
+* @returns {Promise<InitOutput>}
+*/
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;