first commit

examples/README.md

@@ -0,0 +1,157 @@
+# OSIRIS Examples
+
+This directory contains examples demonstrating various features of OSIRIS.
+
+## Prerequisites
+
+Before running the examples, make sure HeroDB is running:
+
+```bash
+cd /path/to/herodb
+cargo run --release -- --dir ./data --admin-secret mysecret --port 6379
+```
+
+## Running Examples
+
+### Basic Usage
+
+Demonstrates core OSIRIS functionality with Notes and Events:
+
+```bash
+cargo run --example basic_usage
+```
+
+**What it shows:**
+- Creating objects with the derive macro
+- Storing objects in HeroDB
+- Querying by indexed fields
+- Retrieving objects by ID
+- Auto-generated index keys
+- Cleanup/deletion
+
+### Custom Object
+
+Shows how to create your own custom object types:
+
+```bash
+cargo run --example custom_object
+```
+
+**What it shows:**
+- Defining custom structs with `#[derive(DeriveObject)]`
+- Using enums in indexed fields
+- Builder pattern for object construction
+- Querying by various indexed fields
+- Updating objects
+- Tag-based organization
+
+## Example Structure
+
+Each example follows this pattern:
+
+1. **Setup** - Connect to HeroDB
+2. **Create** - Build objects using builder pattern
+3. **Store** - Save objects to HeroDB
+4. **Query** - Search by indexed fields
+5. **Retrieve** - Get objects by ID
+6. **Update** - Modify and re-store objects (where applicable)
+7. **Cleanup** - Delete test data
+
+## Key Concepts Demonstrated
+
+### Derive Macro
+
+All examples use the `#[derive(DeriveObject)]` macro:
+
+```rust
+#[derive(Debug, Clone, Serialize, Deserialize, DeriveObject)]
+pub struct MyObject {
+    pub base_data: BaseData,
+    
+    #[index]
+    pub indexed_field: String,
+    
+    pub non_indexed_field: String,
+}
+```
+
+### Indexed Fields
+
+Fields marked with `#[index]` are automatically indexed:
+
+- `Option<T>` - Indexed if Some
+- `BTreeMap<String, String>` - Each key-value pair indexed
+- `OffsetDateTime` - Indexed as date string
+- Enums - Indexed using Debug format
+- Other types - Indexed using Debug format
+
+### Querying
+
+Query by any indexed field:
+
+```rust
+// Query by exact match
+let ids = store.get_ids_by_index("namespace", "field_name", "value").await?;
+
+// Query tags (BTreeMap fields)
+let ids = store.get_ids_by_index("namespace", "tags:tag", "key=value").await?;
+```
+
+### Builder Pattern
+
+All objects support fluent builder pattern:
+
+```rust
+let obj = MyObject::new("namespace".to_string())
+    .set_field1("value1")
+    .set_field2("value2")
+    .add_tag("key", "value");
+```
+
+## Troubleshooting
+
+### Connection Refused
+
+Make sure HeroDB is running on port 6379:
+
+```bash
+redis-cli -p 6379 PING
+```
+
+### Database Not Found
+
+The examples use different database IDs:
+- `basic_usage` - DB 1
+- `custom_object` - DB 2
+
+Make sure these databases are accessible in HeroDB.
+
+### Compilation Errors
+
+Ensure you have the latest dependencies:
+
+```bash
+cargo clean
+cargo build --examples
+```
+
+## Next Steps
+
+After running the examples:
+
+1. Read the [Architecture Documentation](../docs/ARCHITECTURE.md)
+2. Learn about the [Derive Macro](../docs/DERIVE_MACRO.md)
+3. Check out the [Quick Start Guide](../QUICKSTART.md)
+4. Explore the [source code](../src/objects/) for Note and Event implementations
+
+## Creating Your Own Objects
+
+Use the `custom_object` example as a template:
+
+1. Define your struct with `base_data: BaseData`
+2. Add `#[derive(DeriveObject)]`
+3. Mark fields with `#[index]` for automatic indexing
+4. Implement builder methods for convenience
+5. Use `GenericStore` to store and query
+
+Happy coding! 🚀