Vantage

Vantage is an Entity Framework for Rust. With Vantage you can represent your business entities (Client, Order, Invoice, Lead) with native Rust types. Business logic implementation in Vantage and Rust is type-safe and very ergonomic for large code-bases. Ideal for creating facade services, middlewares and microservices or low-code backend UI.

Given your client record:

// Implemented in shared Business Model Library

#[derive(Clone, Debug, Serialize, Deserialize, Default)]
struct Client {
    name: String,
    surname: Option<String>,
    gender: GenderEnum,
    email: Email(String),
    is_paying_client: bool,
    balance: Decimal,
}

Vantage offers the following features out of the box:

DataSet<E> - Interface for a low-level persistence for an entity. There are some internal implementation like CsvFile<E> or Queue<E> which implement DataSet, but more importantly - you can use 3rd party implementations or build your own.
ValueSet<V> - Interface for a uniform persistence without an entity. While this is very similar to strong-typed variant, ValueSet can use serde_json::Value or ciborium::Value to work with schema-less persistences. Example like CsvFile would implement ReadableValueSet<String> while Queue would implement InsertableValueSet<Value>.
Table<E, D> - Struct for storing structured data with some columns. Can be used with NoSQL/SQL database engines, which implement interfaces for TableSource, QuerySource and SelectSource. Table auto-implements DataSet<E> and ValueSet<D::Value>.
Expression<V> - Universal mechanism for constructing query builders. Expressions implement cross-database integration as well as define Selectable interface for minimalistic implementation of a query-builder (SQL-compatible).
ActiveEntity<E> and ActiveRecord<V> - Implementation of ActiveRecord pattern, load the record, pass it around, modify and call record.save() when you are done.
Persistence-specific type systems - Define vendor-specific type sets with vantage-types and create type-boundary systems preventing accidental casting (e.g., Duration to Int) while enabling precise database-native type mapping.

With all of the fundamental blocks and interfaces in place, Vantage can be extended in several ways. First - persistence implementation:

vantage-surrealdb - Implements all interfaces to interact with this powerful multi-modal database with support for custom types, schemaless tables, graph-based queries and live tables. Brings SurrealSelect, SurrealColumn types and also makes use of SurrealType that include Geospatial, 128-bit Decimal and other advanced types. Built on surreal-client.
vantage-redb - Implementation for Redb embedded database, providing some basic features. Perfect as a local cache.

On the other end, Vantage offers some adapters. Those would work with Table / AnyTable and implement generic UI or API component:

vantage-ui-adapters - Implement DataGrid for Tauri, EGui, Cursive, GPUI, RatatUI and Slint frameworks.
vantage-axum* - Implements builder for Axum supporting use of typed or generic tables.
vantage-config - Reads Entity definitions from yaml file, creating type-erased AnyTables.
Vantage Admin* - Desktop Application for Entity management based on yaml config.

(* indicate commercial component)

Vantage 0.4 is almost here. New features include:

Full type system overhaul - Complete redesign of the type mapping system for better database compatibility
Cross-database integration - Seamless queries and operations across different database types
Binary CBOR support - Migrated SurrealDB client from JSON to binary CBOR for improved performance
References(implemented) allowing to traverse between Table<Client> into Table<Order>, even if those tables are stored in different databases.
Expressions(implemented) allow Table columns to be calculated based on subqueries and references.

Features planned for 0.5:

Hooks - Attach 3rd party code plugins into Tables.
Validation - Use standard and advanced validation through a hook mechanism.
Audit - Capture modifications automatically and store in same or a different persistence.

Vantage is planning to add the following features before 1.0:

Aggregators. Use database-vendor specific extensions to build reports declaratively.
GraphQL API adaptor. Build GraphQL APIs on top of Vantage Tables.
Live Tables. Connect CDC or Live events provided by databases with UI adapters or WS APIs.

Example

Vantage is an opinionated framework, which means it will provide guidance on how to describe your business objects in Rust code. Here is a slightly expanded example, which describes how a Client entity can be used with various persistences.

// Implemented in shared Business Model Library

#[derive(Clone, Debug, Serialize, Deserialize, Default)]
struct Client {
    name: String,
    email: String,
    is_paying_client: bool,
    balance: Decimal,
}

impl Client {
    fn new(){ /* ... */};

    fn registration_queue() -> impl InsertableDataSet<Client> {}
    fn admin_api() -> impl DataSet<Client> {}
    fn read_csv(filename: String) -> impl ReadableDataSet<Client> {}
    fn mock() -> MockDataSet<Client> {}

    fn table() -> Table<SurrealDB, Client> {
        Table::new("client", surrealdb())
            .with_column_of::<bool>("is_paying_client")
            .with_many("orders", "client", move || Order::table(surrealdb()))
    }
}

// This is our way to implement Client Table specific features:
pub trait ClientTable {
    fn ref_orders(&self) -> Table<SurrealDB, crate::Order>;
}
impl ClientTable for Table<SurrealDB, Client> {
    fn ref_orders(&self) -> Table<SurrealDB, crate::Order> {
        self.get_ref_as("orders").unwrap()
    }
}

Definitions of your entities can be stored in your own crate, versioned and shared by many other services within your organization. Here is how a typical service might make use of the Client entity:

use model::Client;

async fn register_new_client(client: Client) -> Result<()> {
    let queue = Client::registration_queue(); // Probably KafkaTopic<Client>
    queue.insert(client).await?;
    Ok(())
}

async fn remove_stale_client_orders() -> Result<()> {
    let clients = Client::table()
        .with_condition(clients.is_paying_client().eq(false));

    // Delete orders of affected clients first (stored in MongoDB)
    clients.ref_orders().delete_all();

    // next delete clients (stored in SurrealDB)
    clients.delete_all();

    Ok(())
}

Enterprise software employs hundreds of developers, and anyone can make use of type safety without knowing implementation details. Behind a simple interface of clients and orders, extensions of Vantage allow embedding additional features:

record any operations automatically into audit tables
handle CDC for change tracking or perform necessary validations
use multi-record operations efficiently, like in the case above - MongoDB will perform deletion with a single request.
developer does not need to be mindful, where client table is stored.

Finally, thanks to the amazing Rust type system, the client type will not only implement Client-specific extensions (like ref_order()) but will also implement SurrealDB extensions like search_query(q).

Vantage features

A more comprehensive feature list:

Standard CRUD operations with persistence-abstraction
Implementation of DataSource-specific extensions
Implementation of Entity-specific extensions
Support for Expressions and Query Builder pattern (SQL, SurrealDB)
MultiModal and Json database support (Mongo, GraphQL, SurrealDB)
Data Source abstractions (CSV, Excel, PubSub, APIs)
DataSet building - conditions, query-based expressions and delayed condition lookup
Sync Relationship/References traversal - one-many and many-many - including cross-persistence.
Generic types for DataSet, Table and ActiveRecord over Entity
Support for standard and extended types on table columns
Column flags
(coming in 0.3) Column mapping, validation
Typed queries (known result type) and associated queries (can self-execute)
Type-erased structs for all major traits
Adaptors for UI frameworks, APIs (like axum)
(planned in 0.3) Aggregation, Joins, Expressions.
Yaml-based Entity configurator
Powerful Error handling

Type erasure support

Rust type system is amazing and it is at the core of all Vantage features. In some cases, we want to erase types, for example if we require a generic type interface.

Vantage provides a full set of "Any*" types, which can be used like this:

let clients = Client::admin_api(); // impl DataSet<Client>
let clients = AnyDataSet::new(clients); // AnyDataSet - types erased.

let entities: = vec![clients, orders, ..];

Once type is erased - you can store different entities in same data-structure, implement cross-language SDKs. If you are interested in "Any*" types, see Documentation. The rest of the README will focus on fully typed primitives.

DataSet operations

Crate vantage-dataset introduces ImTableSource, implementing in-memory DataSet implementation.

let in_memory_cache = ImDataSource::new();

let client_cache = ImTable::<User>::new(&in_memory_cache, "clients");
let clients.import(Client::read_csv("clients.csv")).await?;

// Basic loading operation - load one client record
let (id, client) = clients.load_some().await?;
// Next - delete it from memory
clients.delet

Vantage

Install / Use

README

Vantage

Example

Vantage features

Type erasure support

DataSet operations