doc: add readme

Signed-off-by: Jeremie Drouet <[email protected]>

Author: jdrouet

readme.md

@@ -0,0 +1,136 @@
+# browser-fs
+
+A browser-based filesystem implementation for WebAssembly applications using Rust. This crate provides async filesystem operations similar to `std::fs` and `async-fs`, designed specifically for browser environments.
+
+## Features
+
+- 📂 Full filesystem operations (read, write, create, delete)
+- 📁 Directory management (create, list, remove)
+- 🔄 Async I/O support
+- 📊 File metadata handling
+- ⚡ High performance using Web Workers
+- 🛡️ Safe Rust implementation
+- 🌐 Browser-native using File System Access API
+
+## Installation
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+browser-fs = "0.1.0"
+```
+
+## Usage
+
+### Basic File Operations
+
+```rust
+use browser_fs::File;
+use futures_lite::io::AsyncWriteExt;
+
+// Create and write to a file
+async fn write_example() -> std::io::Result<()> {
+    let mut file = File::create("example.txt").await?;
+    file.write_all(b"Hello, world!").await?;
+    file.flush().await?;
+    Ok(())
+}
+
+// Read from a file
+use futures_lite::io::AsyncReadExt;
+
+async fn read_example() -> std::io::Result<String> {
+    let mut file = File::open("example.txt").await?;
+    let mut contents = String::new();
+    file.read_to_string(&mut contents).await?;
+    Ok(contents)
+}
+```
+
+### Directory Operations
+
+```rust
+use browser_fs::{create_dir_all, read_dir};
+use futures_lite::stream::StreamExt;
+
+async fn directory_example() -> std::io::Result<()> {
+    // Create nested directories
+    create_dir_all("/my/nested/directory").await?;
+
+    // List directory contents
+    let mut entries = read_dir("/my/nested").await?;
+    while let Some(entry) = entries.try_next().await? {
+        println!("{}", entry.file_name().to_string_lossy());
+    }
+    Ok(())
+}
+```
+
+### Advanced File Operations
+
+```rust
+use browser_fs::OpenOptions;
+
+async fn advanced_file_example() -> std::io::Result<()> {
+    let mut file = OpenOptions::new()
+        .read(true)
+        .write(true)
+        .create(true)
+        .open("advanced.txt")
+        .await?;
+
+    // File operations...
+    Ok(())
+}
+```
+
+## Requirements
+
+- WebAssembly environment
+- Modern browser with File System Access API support
+- Must run in a Web Worker context
+
+## Limitations
+
+- Maximum file size of 4GB (due to wasm32 constraints)
+- Must run in a Web Worker (not available on main thread)
+- Browser security restrictions apply
+- Single file handle at a time per file
+
+## 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.
+
+Please make sure to update tests as appropriate.
+
+## Testing
+
+Run the test suite:
+
+```bash
+wasm-pack test --headless --firefox
+```
+
+## License
+
+MIT License
+
+## Credits
+
+This project is inspired by the excellent work done in:
+- [async-fs](https://docs.rs/async-fs/)
+- [web-fs](https://docs.rs/web-fs/)
+
+## Future Plans
+
+- [ ] Better concurrent file access
+- [ ] Better error messages and handling
+
+## Safety
+
+This crate uses `#![forbid(unsafe_code)]` to ensure 100% safe Rust.
+
+## Performance
+
+The crate is designed to be efficient while working within browser constraints. All operations are asynchronous and use modern browser APIs for optimal performance.