From b246256911e33f21c95db4aa6e22003b86bc940d Mon Sep 17 00:00:00 2001
From: Tarek <tareknaser360@gmail.com>
Date: Thu, 8 Aug 2024 22:59:43 +0300
Subject: [PATCH] docs(fs-index): add README and example for the crate

Signed-off-by: Tarek <tareknaser360@gmail.com>
---
 fs-index/README.md                  | 35 ++++++++++++++++++++++
 fs-index/examples/resource_index.rs | 46 +++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 fs-index/README.md
 create mode 100644 fs-index/examples/resource_index.rs

diff --git a/fs-index/README.md b/fs-index/README.md
new file mode 100644
index 00000000..9253375a
--- /dev/null
+++ b/fs-index/README.md
@@ -0,0 +1,35 @@
+# fs-index
+
+`fs-index` is a Rust crate for managing and indexing file system resources. It provides a flexible and efficient way to track changes, query resources, and keep files in sync across multiple devices or locations.
+
+Originally developed for the ARK framework to support local-first applications, `fs-index` can also be used in various scenarios including backup systems, content management, and more.
+
+## Features
+
+The most important struct in this crate is `ResourceIndex` which comes with:
+
+- **Reactive API**
+  - `update_all`: Method to update the index by rescanning files and returning changes (additions/deletions).
+- **Snapshot API**
+  - `get_resources_by_id`: Query resources from the index by ID.
+  - `get_resource_by_path`: Query a resource from the index by its path.
+
+## Custom Serialization
+
+The `ResourceIndex` struct includes a custom serialization implementation to avoid writing a large repetitive index file with double maps.
+
+## Tests and Benchmarks
+
+- Unit tests are located in `src/tests.rs`.
+- The benchmarking suite is in `benches/resource_index_benchmark.rs`, benchmarking all methods of `ResourceIndex`.
+  - Run benchmarks with `cargo bench`.
+
+## Examples
+
+To get started, take a look at the examples in the `examples/` directory.
+
+To run a specific example:
+
+```shell
+cargo run --example resource_index
+```
diff --git a/fs-index/examples/resource_index.rs b/fs-index/examples/resource_index.rs
new file mode 100644
index 00000000..3f5cb797
--- /dev/null
+++ b/fs-index/examples/resource_index.rs
@@ -0,0 +1,46 @@
+use std::path::Path;
+
+use anyhow::Result;
+
+use dev_hash::Blake3;
+use fs_index::ResourceIndex;
+
+/// A simple example of how to use [`ResourceIndex`] to index a directory.
+fn main() -> Result<()> {
+    // Create a new `ResourceIndex` from the directory "test-assets" using
+    // blake3 as the hashing algorithm.
+    let mut index: ResourceIndex<Blake3> =
+        ResourceIndex::build(Path::new("test-assets"))?;
+
+    // Print the indexed resources.
+    for resource in index.resources() {
+        println!("{:?}", resource);
+    }
+
+    // Save the index to a file.
+    index.store()?;
+
+    // Get resources by their id.
+    let id = Blake3(
+        "172b4bf148e858b13dde0fc6613413bcb7552e5c4e5c45195ac6c80f20eb5ff5"
+            .to_string(),
+    );
+    let resources = index.get_resources_by_id(&id).ok_or_else(|| {
+        anyhow::anyhow!("Resource with id {:?} not found", id)
+    })?;
+    for resource in resources {
+        println!("{:?}", resource);
+    }
+
+    // Get resources by their path.
+    let path = Path::new("lena.jpg");
+    let resource = index.get_resource_by_path(path).ok_or_else(|| {
+        anyhow::anyhow!("Resource with path {:?} not found", path)
+    })?;
+    println!("{:?}", resource);
+
+    // Update the index.
+    index.update_all()?;
+
+    Ok(())
+}