redis-om

A Rust/Redis ORM-style library that simplify the development process and reduce the amount of boilerplate code needed to build programs that leverage [redis] powerful capabilities and use cases.

Status: WIP, fully testsed, possible breaking changes, stay tuned

Features

• ORM-style API to define/manipulate [redis data structures] (e.g. hashes, json, streams) using [derive macros].
• Automatic serialization/desalinization between Redis data and rust objects.
• Interoperability with serde, e.g. using rename, rename_all or serde.
• Nested hash datatype support (e.g. list.1 or nested models account.balance as keys).

Usage

• Getting Started
• Using Redis's Hash Datatype
• Using Redis's Json Datatype
• Using Redis's Stream Datatype

Roadmap

• 0.1.0
  • [x] Enable users to define and derive Hash Model with most common methods
  • [x] Enable users to define and derive JSON Model with most common methods
  • [x] Enable users to define and derive streams with managers to publish-to/read-from them.
  • [x] Support users to choose between asynchronous and synchronous runtime.
• 0.2.0
  • [ ] Enable Multi-Stream Manager Support to enable users to combine multiple RedisModels.
  • [ ] Support Serializing/deserializing HashModel complex fields using serde.
  • [ ] Support RedisSearch and provide query-building API.
  • [ ] .....
• 0.3.0
  • [ ] Support validation of struct fields and enum values (most likely using [validator library]).
  • [ ] .....

Getting Started

```toml redis-om = { version = "*" }

TLS support with async-std

redis-om = { version = "*", features = ["tls"] }

async support with tokio

redis-om = { version = "*", features = ["tokio-comp"] }

async support with async-std

redis-om = { version = "*", features = ["async-std-comp"] }

TLS and async support with tokio

redis-om = { version = "*", features = ["tokio-native-tls-comp"] }

TLS support with async-std

redis-om = { version = "*", features = ["async-std-tls-comp"] } ```

Hash

```rust ignore use redis_om::HashModel;

[derive(HashModel, Debug, PartialEq, Eq)]

struct Customer { id: String, firstname: String, lastname: String, email: String, bio: Option, interests: Vec }

// Now that we have a Customer model, let's use it to save customer data to Redis.

// First, we create a new Customer object: let mut jane = Customer { id: "".into(), // will be auto generated when it's empty firstname: "Jane".into(), lastname: "Doe".into(), email: "jane.doe@example.com".into(), bio: Some("Open Source Rust developer".into()), interests: vec!["Books".to_string()], };

// Get client let client = redisom::Client::open("redis://127.0.0.1/").unwrap(); // Get connection let mut conn = client.getconnection().unwrap();

// We can save the model to Redis by calling save(): jane.save(&mut conn).unwrap();

// Expire the model after 1 min (60 seconds) jane.expire(60, &mut conn).unwrap();

// Retrieve this customer with its primary key let jane_db = Customer::get(&jane.id, &mut conn).unwrap();

// Delete customer Customer::delete(&jane.id, &mut conn).unwrap();

asserteq!(janedb, jane); ```

Json

redis-om support json data type through redis_om::JsonModel. It requires that the type derives serde::Deserialize as well as serde::Serialize.

```rust ignore use redis_om::JsonModel; use serde::{Deserialize, Serialize};

[derive(Deserialize, Serialize, Debug, PartialEq, Eq)]

struct AccountDetails { balance: String, }

[derive(JsonModel, Deserialize, Serialize, Debug, PartialEq, Eq)]

struct Account { id: String, firstname: String, lastname: String, details: AccountDetails, }

// Now that we have a Account model, let's use it to save account data to Redis.

// First, we create a new Account object: let mut john = Account { id: "".into(), // will be auto generated when it's empty firstname: "John".into(), lastname: "Doe".into(), details: AccountDetails { balance: "1.5m".into(), } };

// Get client let client = redisom::Client::open("redis://127.0.0.1/").unwrap(); // Get connection let mut conn = client.getconnection().unwrap();

// We can save the model to Redis by calling save(): john.save(&mut conn).unwrap();

// Expire the model after 1 min (60 seconds) john.expire(60, &mut conn).unwrap();

// Retrieve this account with its primary key let john_db = Account::get(&john.id, &mut conn).unwrap();

// Delete customer Account::delete(&john.id, &mut conn).unwrap();

asserteq!(johndb, john); ```

Stream

redis-om support json data type through redis_om::StreamModel. It requires that any nested type to derives redis_om::RedisTransportValue.

```rust ignore use redis_om::{RedisTransportValue, StreamModel};

/// An enum of room service kind

[derive(RedisTransportValue)]

pub enum RoomServiceJob { Clean, ExtraTowels, ExtraPillows, FoodOrder, }

/// An enum of room service kind

[derive(StreamModel)]

[redis(key = "room")] // rename stream key in redis

pub struct RoomServiceEvent { status: String, room: usize, job: RoomServiceJob, }

// Get client let client = redisom::Client::open("redis://127.0.0.1/").unwrap(); // Get connection let mut conn = client.getconnection().unwrap();

// Create a new instance of Room service Event Manager with consumer group. // Note: consumer name is auto generated, // use RoomServiceEventManager::newwithconsumer_name, // for a custom name let manager = RoomServiceEventManager::new("Staff");

// Ensure the consumer group manager.ensuregroupstream(&mut conn).unwrap();

// Create new event let event = RoomServiceEvent { status: "pending".into(), room: 3, job: RoomServiceJob::Clean, };

// Publish the event to the RoomServiceEvent redis stream RoomServiceEventManager::publish(&event, &mut conn).unwrap();

// Read with optional readcount: Option, blockinterval: Option let read = manager.read(None, None, &mut conn).unwrap();

// Get first incoming event let incomingevent = read.first().unwrap(); // Get first incoming event data let incomingeventdata = incomingevent.data::().unwrap(); // Acknowledge that you received the event, so other in the consumers don't get it RoomServiceEventManager::ack(manager.groupname(), &[&incomingevent.id], &mut conn).unwrap();

asserteq!(incomingevent_data.room, event.room); ```