entity-rs: Library & macros for entity data structures
A simplistic framework based on TAO, Facebook's distributed database for Social Graph.
Requires Rust 1.49+.
Getting Started
Installation
Import Entity into your project by adding the following line to your
Cargo.toml. entity_macros
contains the macros needed to derive and/or
transform your data to be compatible with supported databases and queries.
[]
= "0.3.0"
For most use cases, you will want to also import the macros, which will bring
in the entity_macros
crate:
[]
= { = "0.3.0", = ["macros"] }
Defining data using macros
The following is an example of defining a User
data structure that contains
an age and name field as well as references to many other User
instances
under the edge name friends.
use simple_ent;
This generates a variety of trait implementations and additional data
structures to work with the User
struct against any database.
Loading an ent by id
use EntLoader;
let db = /* entity::WeakDatabaseRc instance */;
// Loads the user from the provided database reference
let user = load_from_db_strict.expect;
// Loads the user from the globally-set database
let user = load_strict.expect;
Accessing ent fields
Every object implementing the Ent
trait is able to access a variety of
common data including abstract field information:
use ;
let user = /* User instance */;
// Access a list of all field names
assert_eq!;
// Access individual field values, which are exposed using entity's
// generic Value enum
assert_eq!;
assert_eq!;
When using macros to generate an ent, typed accessors are also provided as seen below:
let user = /* User instance */;
// Accesses fields and returns a reference to their actual type NOT
// wrapped in entity's generic Value enum
assert_eq!;
assert_eq!;
Accessing ent edges
Every object implementing the Ent
trait is able to access a variety of
abstract edge information:
use ;
let user = /* User instance */;
// Access a list of all edge names
assert_eq!;
// Access specific edge information (does not load it)
assert_eq!;
// Load an edge by name, returning a Vec<Box<dyn Ent>>
let friends: = user.load_edge.expect;
When using macros to generate an ent, typed edge accessors are also provided as seen below:
let user = /* User instance */;
// Access the ids of ents referenced by the edge
assert_eq!;
// Load the ents referenced by the edge into memory
let friends: = user.load_friends.expect;
Querying an ent
Alongside loading ents by their ids, the full suite that entity-rs
provides
also includes the ability to query arbitrary data structures using a concept of
queries and associated predicates:
use ;
let db = /* WeakDatabaseRc instance */;
// Produce a new query to search for ents with an age field that is 18 or higher
let ents: = default
.where_field
.execute_with_db
.expect;
// If the global database has been configured, can also be used in this manner
let ents: = default
.where_field
.execute
.expect;
When using macros to generate an ent, a companion query struct that
provides stricter types on queries is also created using the name
{Ent}Query
:
use ;
let db = /* WeakDatabaseRc instance */;
// Produce a new query to search for ents with an age field that is 18 or higher
let users: = query
.where_age
.execute_with_db
.expect;
// If the global database has been configured, can also be used in this manner
let users: = query
.where_age
.execute
.expect;
Examples
async-graphql
: example of usingentity-rs
withasync-graphql
inmemory
: example of usingentity-rs
with a custom inmemory databasesled
: example of usingentity-rs
withsled
Feature Flags
Entity provides a few feature flags:
global
- Enables use of a database stored as a global variable, providing shortcuts in creating and retrieving ents.macros
- Enables macros for deriving ents and exposing a cleaner declarative API for ents. (Importsentity_macros
directly)serde-1
- Provides serde serialization module and associated functionality for ents through the use of typetag. This will require that all ents implement Serialize and Deserialize.- Requires
serde
andtypetag
to be included in dependencies.
- Requires